> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Run Atoll as a remote Model Context Protocol server for agents, ChatGPT-style apps, and environments without local CLI access.

Use `@atollhq/mcp-server` when an agent needs Atoll tools but cannot run a local shell command, read a local CLI profile, or share filesystem state with you.

The MCP server calls the Atoll API directly and exposes CLI-like workflows as MCP tools.

## When to use it

Use the MCP server for:

* Remote agents that can call MCP tools but cannot install `@atollhq/cli`
* ChatGPT-style apps that need an HTTPS MCP endpoint
* Hosted automation where secrets live in the deployment environment
* Single-tenant internal deployments that should use one Atoll API key

Use the CLI instead when the agent runs on your machine and can use local profiles.

## Install

```bash theme={null}
npm install -g @atollhq/mcp-server
```

## Run as a remote server

Start the server:

```bash theme={null}
PORT=8787 atoll-mcp
```

The server exposes:

| Route         | Purpose                                 |
| ------------- | --------------------------------------- |
| `POST /mcp`   | MCP Streamable HTTP endpoint            |
| `GET /health` | Health check for deployments and probes |

Remote clients should send the Atoll API key on each MCP request:

```http theme={null}
Authorization: Bearer sk_atoll_...
```

<Warning>
  Treat `sk_atoll_...` keys as secrets. Do not put them in client-side code, public ChatGPT component JavaScript, logs, or task comments.
</Warning>

## Single-tenant deployment

For an internal deployment that serves one Atoll org, set environment variables in the hosting platform:

```bash theme={null}
export ATOLL_API_KEY="sk_atoll_..."
export ATOLL_ORG_ID="org-uuid"
export ATOLL_BASE_URL="https://atollhq.com"
```

If a tool call omits `org_id`, the server uses `ATOLL_ORG_ID`. If `ATOLL_ORG_ID` is not set and the key can access exactly one org, the server uses that org. If the key can access multiple orgs, the tool returns an error asking for `org_id`.

## Local stdio mode

Use stdio mode for local MCP clients and debugging:

```bash theme={null}
ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid atoll-mcp --stdio
```

## Tool coverage

The MCP tools use the `atoll_` prefix to avoid collisions with other MCP servers.

| Area                       | Tools                                                                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Orientation                | `atoll_get_heartbeat`, `atoll_get_auth_context`, `atoll_list_orgs`                                                                                                 |
| Tasks                      | `atoll_list_issues`, `atoll_get_issue`, `atoll_create_issue`, `atoll_update_issue`, `atoll_archive_issue`, `atoll_unarchive_issue`                                 |
| Comments                   | `atoll_list_comments`, `atoll_add_comment`                                                                                                                         |
| Projects                   | `atoll_list_projects`, `atoll_get_project`, `atoll_create_project`                                                                                                 |
| Goals and KPIs             | `atoll_list_goals`, `atoll_create_goal`, `atoll_list_kpis`, `atoll_record_kpi_snapshot`, `atoll_create_kpi_http_sync_draft`, `atoll_validate_kpi_http_sync_config` |
| Initiatives and milestones | initiative list/create/update/link tools, initiative target CRUD/link tools, `atoll_list_milestones`, `atoll_create_milestone`, `atoll_upsert_milestone`           |
| Dependencies and webhooks  | dependency tools, webhook tools                                                                                                                                    |
| Advanced API use           | `atoll_api_request`                                                                                                                                                |

Use `atoll_get_heartbeat` first when an autonomous agent needs to decide what to do next.

`atoll_add_comment` accepts `mentions: [{ "member_id": "member-id" }]` so remote agents can mention humans or agents by stable Atoll org member ID. Use this structured field instead of generated Markdown when an agent or integration needs verifiable mention fanout. `atoll_update_issue` accepts `comment_body` for durable status-update comments, but structured mention fanout through MCP is exposed on `atoll_add_comment`.

Use `atoll_update_issue` with `comment_body` when applying a heartbeat `start_work` recommendation so the KPI, initiative, initiative target, why-now, expected impact, first step, and success criteria remain as a durable issue comment.

Use initiative target tools for initiative-specific commitments. Progress targets track outputs; gate targets represent launch prerequisites and should be treated as due/blocked state, not fractional KPI pace.

KPI HTTP sync tools are draft/validate only and require the destination host to already be exactly allowlisted by a human admin. Agents must not include secret values, API keys, cookies, raw third-party responses, or query-string credentials. The generic `atoll_api_request` tool rejects KPI HTTP sync and sync policy routes; human admins must use Atoll for exact-host allowlists, secret entry, dry-run, publish, disable, and run-now snapshot writes.

## Skills stay separate

Atoll skills and the MCP server solve different problems:

* Skills teach an agent how to reason about Atoll and its workflows.
* The MCP server gives an agent remote tools for reading and writing Atoll data.

Keep using the skill package for your agent environment when available. Use the MCP server when the environment needs remote tool access.

See [Agent skills](/integrations/agent-skills) for skill packages.

## ChatGPT app path

OpenAI's Apps SDK uses MCP as the tool layer for ChatGPT apps. To turn Atoll into a production ChatGPT app:

1. Deploy `@atollhq/mcp-server` at a public HTTPS URL.
2. Add OAuth for user-specific Atoll access instead of asking users to paste API keys.
3. Add Apps SDK UI resources for views such as heartbeat, project board, issue detail, and KPI trend panels.
4. Attach UI templates to the highest-value tools, starting with `atoll_get_heartbeat`.
5. Test the app from ChatGPT developer mode before submitting it for review.

Useful OpenAI references:

* [Apps SDK quickstart](https://developers.openai.com/apps-sdk/quickstart)
* [Build an MCP server](https://developers.openai.com/apps-sdk/build/mcp-server)
* [Authentication](https://developers.openai.com/apps-sdk/build/auth)

## Verify a deployment

Check the health endpoint:

```bash theme={null}
curl -i https://mcp.example.com/health
```

Expected body:

```json theme={null}
{
  "ok": true,
  "service": "atoll-mcp-server"
}
```

Then connect an MCP client to:

```text theme={null}
https://mcp.example.com/mcp
```