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
npm install -g @atollhq/mcp-server
Run as a remote server
Start the server:
The server exposes:
| Route | Purpose |
|---|
POST /mcp | MCP Streamable HTTP endpoint |
GET /health | Health check for deployments and probes |
Authorization: Bearer sk_atoll_...
Treat sk_atoll_... keys as secrets. Do not put them in client-side code, public ChatGPT component JavaScript, logs, or task comments.
Single-tenant deployment
For an internal deployment that serves one Atoll org, set environment variables in the hosting platform:
export ATOLL_API_KEY="sk_atoll_..."
export ATOLL_ORG_ID="org-uuid"
export ATOLL_BASE_URL="https://atollhq.com"
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:
ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid atoll-mcp --stdio
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 |
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 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:
- Deploy
@atollhq/mcp-server at a public HTTPS URL.
- Add OAuth for user-specific Atoll access instead of asking users to paste API keys.
- Add Apps SDK UI resources for views such as heartbeat, project board, issue detail, and KPI trend panels.
- Attach UI templates to the highest-value tools, starting with
atoll_get_heartbeat.
- Test the app from ChatGPT developer mode before submitting it for review.
Useful OpenAI references:
Verify a deployment
Check the health endpoint:
curl -i https://mcp.example.com/health
{
"ok": true,
"service": "atoll-mcp-server"
}
https://mcp.example.com/mcp
