@atollhq/mcp-server

Remote-capable MCP server for Atoll. It mirrors the core @atollhq/cli workflows as MCP tools while calling the Atoll REST API directly, so clients do not need local Atoll CLI profiles or filesystem access.

Install

npm install -g @atollhq/mcp-server

Remote HTTP

PORT=8787 atoll-mcp

The server exposes:

• POST /mcp -- MCP Streamable HTTP endpoint
• GET /health -- JSON health check

Remote clients should send the Atoll API key per request:

Authorization: Bearer sk_atoll_...

For single-tenant deployments, set:

export ATOLL_API_KEY="sk_atoll_..."
export ATOLL_ORG_ID="org-uuid"
export ATOLL_BASE_URL="https://atollhq.com"

When org_id is omitted from a tool call, the server uses ATOLL_ORG_ID. If that is not set, it uses the only org visible to the API key. If multiple orgs are visible, tools return an error asking for org_id.

Local stdio

ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid atoll-mcp --stdio

Tool coverage

The MCP surface uses service-prefixed tool names to avoid collisions:

• atoll_get_heartbeat
• atoll_list_orgs, atoll_get_auth_context
• atoll_list_issues, atoll_get_issue, atoll_create_issue, atoll_update_issue, atoll_archive_issue, atoll_unarchive_issue
• atoll_list_comments, atoll_add_comment
• atoll_list_projects, atoll_get_project, atoll_create_project
• atoll_list_goals, atoll_get_goal, atoll_create_goal, atoll_update_goal
• atoll_list_kpis, atoll_get_kpi, atoll_create_kpi, atoll_update_kpi, atoll_list_kpi_snapshots, atoll_record_kpi_snapshot
• atoll_create_kpi_http_sync_draft, atoll_validate_kpi_http_sync_config for draft-only KPI sync setup
• atoll_list_initiatives, atoll_get_initiative, atoll_create_initiative, atoll_update_initiative, initiative link tools
• atoll_list_milestones, atoll_create_milestone, atoll_upsert_milestone
• atoll_list_dependencies, atoll_add_dependency, atoll_remove_dependency
• atoll_list_webhooks, atoll_create_webhook, atoll_delete_webhook
• atoll_send_feedback
• atoll_api_request for advanced REST endpoints not yet promoted to a first-class tool

atoll_update_issue accepts comment_body and commentBody with status updates. Use this 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 while the issue status changes.

atoll_add_comment accepts one-level reply_to_comment_id, structured mentions, and explicit source_metadata (harness, thread/session ID, optional host ID). The server does not infer harness IDs; callers must supply them and must not put secrets in routing metadata.

KPI HTTP sync admin routes are intentionally blocked from atoll_api_request. Use atoll_create_kpi_http_sync_draft or atoll_validate_kpi_http_sync_config for agent-authored drafts; human admins must use Atoll for exact-host allowlists, secret entry, dry-runs, publishing, disabling, and run-now snapshot writes.

Skills packaging

Keep Atoll skills separate from this MCP server.

The MCP package should stay runtime-focused: transport, auth, validation, Atoll API calls, and structured tool responses. Skills are client-side agent guidance and already differ by environment (skill-claude, skill-codex, skill-gemini, ClawHub). The server exposes an atoll://skills/packaging resource that explains this decision to MCP clients, but it does not bundle local skill files.

ChatGPT app path

OpenAI’s Apps SDK builds ChatGPT apps around an MCP server plus optional UI components. The next step is to make this package deployable at a public HTTPS URL, add OAuth or API-key setup for ChatGPT users, then add Apps SDK resources/components for richer Atoll views such as heartbeat, board, issue detail, and KPI trend panels.

Useful official starting points:

• https://developers.openai.com/apps-sdk/
• https://developers.openai.com/apps-sdk/build/mcp-server
• https://developers.openai.com/apps-sdk/build/components
• https://developers.openai.com/apps-sdk/build/auth

Development

bun test packages/mcp-server/test/*.test.ts
bun run --cwd packages/mcp-server build