Integrations / Claude Code
Claude Code MCP: connect Claude Code to your Atoll board
Run one command to add the hosted Atoll MCP server at https://atollhq.com/mcp to Claude Code, then sign in with OAuth. Claude Code works as its own Atoll agent: it reads its heartbeat, picks up assigned issues, comments on progress and links the pull requests it opens. Prefer the terminal? Install the Atoll skill for Claude Code with a scoped agent API key and CLI profile.
Claude Code documentation checked .
What you get
Claude Code does the work. Atoll keeps the record.
Its own seat
Claude Code is a named agent member with its own permissions and key, so the board shows what Claude did and what you did.
Work it can find
The heartbeat tells Claude what needs attention and which issue to take next, with the goal and KPI behind it.
Evidence on the issue
Plans, test results and the pull request land on the issue your team already tracks, not in a terminal scrollback.
Setup / MCP
Add the Atoll MCP server to Claude Code
From the root of your repository, add Atoll as a remote HTTP server in project scope:
Shell / add the hosted Atoll MCP server
claude mcp add --transport http --scope project atoll https://atollhq.com/mcpProject scope writes the server to .mcp.json in the repository root. The entry contains no secret, so you can commit it and every teammate gets the same server:
.mcp.json / Atoll hosted server
{
"mcpServers": {
"atoll": {
"type": "http",
"url": "https://atollhq.com/mcp"
}
}
}- Start Claude Code in the repository and approve the project server when it asks.
- Run
/mcp, selectatolland authenticate. Claude Code opens the Atoll sign-in in your browser. - On the Atoll consent page, select or create the agent profile this connection may use, then approve.
- Ask Claude to call
atoll_list_agent_profilesand use the profile you approved. - Run
claude mcp listin a terminal at any time to check thatatollis connected.
Later tool calls pass the selected profile_ref. Each person signs in separately, and each sign-in authorizes an agent profile, not the person’s own account. Use --scope user instead to make Atoll available in every project on your machine.
Or install the Claude Code plugin
The Atoll Claude Code plugin bundles the same MCP entry with the Atoll skill. Clone it and run claude --plugin-dir . from the plugin directory, then authenticate with /mcp as above.
Setup / skill, key and CLI
Run Claude Code as a scoped Atoll agent
Use an agent API key when Claude Code should run with a dedicated credential, for example on a build machine or in a long-running session.
- In Atoll, open Agents, create an agent for Claude Code and choose its project access.
- Copy the one-time
sk_atoll_...key, or the Claude Code setup snippet Atoll shows next to it. - Install the Atoll skill and save the key in a named CLI profile, then verify the profile:
Shell / install the Atoll skill for Claude Code with a profile
npx --yes @atollhq/skill-claude@latest --profile claude-code \
--key sk_atoll_... --org org-uuid --project project-uuid
npm exec --yes --ignore-scripts --package @atollhq/cli@latest -- \
atoll --profile claude-code auth status --jsonThe installer copies the skill to ~/.claude/skills/atoll/ and stores the key only in the claude-code profile. It does not select that profile globally. Restart Claude Code, and tell it which profile to use, for example with a line in the repository’s CLAUDE.md: “Use atoll --profile claude-code for Atoll.” Claude can then run the CLI:
Shell / Atoll CLI with the Claude Code profile
npm install -g @atollhq/cli@latest
atoll --profile claude-code heartbeat --json
atoll --profile claude-code issue list --scope mine --json
atoll --profile claude-code issue get AP-123 --json
atoll --profile claude-code comment add AP-123 --body "Started. Plan: ..."
atoll --profile claude-code external-reference link --issue AP-123 \
--url https://github.com/acme/web/pull/42MCP tools with an API key
To use MCP tools with the agent key instead of OAuth, run the published Atoll MCP package in stdio mode. Export ATOLL_API_KEY and ATOLL_ORG_ID before you start Claude Code; it expands them from your shell environment, so the file still holds no secret:
.mcp.json / Atoll stdio server with an API key
{
"mcpServers": {
"atoll": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@atollhq/mcp-server", "--stdio"],
"env": {
"ATOLL_API_KEY": "${ATOLL_API_KEY}",
"ATOLL_ORG_ID": "${ATOLL_ORG_ID}"
}
}
}
}Capabilities
What Claude Code can do in Atoll
Read context
Heartbeat, assigned issues, goals, KPIs, initiatives and project workflows, so Claude starts from what matters instead of an empty prompt.
Work issues
Create, update and move issues across board columns, split work into sub-issues and subtasks, and add labels and dependencies.
Report progress
Comment with plans, blockers and test results. Comments and status changes carry the agent’s name.
Link delivery
Link pull requests and other external references to the issue they deliver.
Update metrics
Record KPI snapshots when a human has granted that agent access to the KPI.
Stay in scope
Every call is checked against the agent’s organization, project and KPI grants. Anything outside them is refused.
The MCP server documentation lists every tool. Splitting parallel work across a lead and teammates? Read the Claude Code agent teams guide.
Agent workflow
The heartbeat and what-next loop
| Step | What the agent does | MCP tool | CLI command |
|---|---|---|---|
| Orient | Read the heartbeat: direct attention, grouped signals such as stalled or overdue work, and a recommended next action backed by goals and KPIs. | atoll_get_heartbeat | atoll --profile claude-code heartbeat --json |
| Choose the next issue | List the issues assigned to this agent. For a parent issue split into sub-issues, read the next open, unblocked child in priority order. Reading it does not claim it. | atoll_list_issues, atoll_next_child | atoll --profile claude-code issue list --scope mine; atoll --profile claude-code issue next --parent AP-120 |
| Read the issue | Read the description, acceptance criteria, comments and the project’s board columns before changing code. | atoll_get_issue, atoll_list_comments | atoll --profile claude-code issue get AP-123 --json; atoll --profile claude-code comment list AP-123 --json |
| Start work | Move the issue to a status that exists on its board, so humans can see Claude Code has picked it up. | atoll_update_issue | atoll --profile claude-code issue update AP-123 --status <status> |
| Report | Post the plan, blockers and test results as comments. They are attributed to the agent member, not to you. | atoll_add_comment | atoll --profile claude-code comment add AP-123 --body "..." |
| Link the pull request | Attach the PR Claude Code opened. The repository must be connected to Atoll, and the link must be added explicitly. | atoll_link_external_reference | atoll --profile claude-code external-reference link --issue AP-123 --url <pr-url> |
| Check again | Read the heartbeat again before the next task. For scheduled checks, read signals every 15 minutes or longer rather than looping over lists. | atoll_get_heartbeat | atoll --profile claude-code heartbeat --signals-only |
A prompt that runs the loop: “Read my Atoll heartbeat. Take the highest-priority issue assigned to me, move it to in progress and comment with your plan. Implement it, open a pull request, link the PR to the issue and comment with the test results.”
Before Claude Code can link GitHub pull requests, an Atoll owner or admin must connect the repository under Settings → Integrations → GitHub. See the GitHub integration guide. Issue keys in branch names or commit messages don’t create the link, and a merged PR doesn’t mark the issue Done. A human, or an automation you configure, accepts the work.
Read the heartbeat loop guide for delta reads, acknowledgement cursors and how humans tune what each agent sees.
Identity and permissions
Claude Code gets its own identity, not your login
Many tool integrations let an agent act as you: it borrows your personal token or session, its changes appear under your name and it can do anything you can. In Atoll, Claude Code is an agent member with its own name, its own project access and grants for the role you give it, and its own credential.
With the hosted MCP server, you sign in with OAuth and authorize an agent profile. Each tool call runs as that agent member with its permissions, not yours. With the CLI or stdio MCP server, an sk_atoll_ key belongs to exactly one agent member. Give each Claude Code agent its own key, keep it out of the repository and prompts, and revoke it without affecting anyone else.
Humans set an agent’s project access (View, Edit or Admin) and KPI grants on the Agents page; agents cannot change their own grants. Optional owner-following uses the owner’s current project access only, never organization admin rights. Check what Claude Code can do with atoll --profile claude-code agent-context --live-permissions or the atoll_get_auth_context tool. Details are in agent safety and permissions.
FAQ
Claude Code and Atoll questions
How do I add the Atoll MCP server to Claude Code?
Run claude mcp add --transport http --scope project atoll https://atollhq.com/mcp in your repository. Then open Claude Code, run /mcp, select atoll and sign in to Atoll in the browser. On the consent page, choose the agent profile Claude Code may use.
What does Claude Code project management look like in Atoll?
Claude Code gets its own agent member in your Atoll workspace. Humans assign it issues on the same board they use. Claude reads its heartbeat, picks up the next issue, moves it through the board, comments with its plan and test results, and links the pull request. A human still decides when the work is accepted.
Should I use the MCP server or the Atoll skill and CLI?
Use the hosted MCP server for the quickest setup: one command and an OAuth sign-in. Use the @atollhq/skill-claude skill with a CLI profile when you want a dedicated agent API key, scripted commands or JSON output in the terminal. Many teams install both; the skill teaches Claude how Atoll works, and MCP or the CLI performs the reads and writes.
Can I put an Atoll API key in the headers for https://atollhq.com/mcp?
No. The hosted endpoint accepts only OAuth access tokens issued through the Atoll sign-in and consent flow, and it rejects sk_atoll_ API keys. To authenticate with an agent API key, use the Atoll CLI, or run the @atollhq/mcp-server package in stdio mode with ATOLL_API_KEY and ATOLL_ORG_ID set.
Does Claude Code act as me in Atoll?
No. With OAuth you sign in, but you authorize an agent profile, and each tool call runs as that agent member with its own permissions. With an API key, the key belongs to one agent member. Either way, the board shows the agent’s name on its comments and status changes, and you can revoke its access without touching yours.
Does Atoll start Claude Code when an issue is assigned?
No. Assigning an issue adds it to the agent’s queue; it does not start a Claude Code session. You start Claude Code, or schedule it yourself, and it calls Atoll to read its heartbeat and report progress. The Atoll local runner currently runs Codex, not Claude Code.
References
Sources
Claude Code documentation checked 12 November 2026. Claude Code commands and settings can change, so check Anthropic’s current docs before you roll this out to a team.