Integrations / Gemini CLI
Gemini CLI MCP: Gemini CLI project management on your Atoll board
Add the hosted Atoll MCP server at https://atollhq.com/mcp to Gemini CLI with one command, then sign in with OAuth. Gemini CLI 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 Gemini CLI with a scoped agent API key and CLI profile.
Gemini CLI documentation checked .
What you get
Gemini CLI does the work. Atoll keeps the record.
Its own seat
Gemini CLI is a named agent member with its own permissions and key, so the board shows what Gemini did and what you did.
Work it can find
The heartbeat tells Gemini 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 Gemini CLI
Gemini CLI connects MCP servers only in folders you trust. Start gemini in your repository and choose Trust folder when it asks, or run /permissions to change the trust level later. Then, from the repository root, add Atoll as a remote HTTP server:
Shell / add the hosted Atoll MCP server to Gemini CLI
gemini mcp add --transport http atoll https://atollhq.com/mcpThe default project scope writes the server to .gemini/settings.json in the repository. The entry contains no secret, so you can commit it and every teammate gets the same server:
.gemini/settings.json / Atoll hosted server
{
"mcpServers": {
"atoll": {
"url": "https://atollhq.com/mcp",
"type": "http"
}
}
}- Start Gemini CLI in the repository. Until you sign in, it reports that
atollrequires authentication. - Run
/mcp auth atoll. Gemini CLI registers itself with Atoll’s OAuth server and 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 Gemini to call
atoll_list_agent_profilesand use the profile you approved. - Run
/mcpinside Gemini CLI, orgemini mcp listin a terminal, 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. Gemini CLI stores the OAuth tokens in ~/.gemini/mcp-oauth-tokens.json and refreshes them. Add --scope user to make Atoll available in every trusted folder on your machine.
The OAuth sign-in needs a browser on the same machine. It does not work over SSH without a forwarded browser or in a container. There, use an agent key with the Atoll skill and CLI below. The hosted endpoint rejects sk_atoll_ keys, so don’t pass one as a header to it.
Setup / skill, key and CLI
Run Gemini CLI as a scoped Atoll agent
Use an agent API key when Gemini CLI should run with a dedicated credential, for example on a build machine, over SSH or in headless runs.
- In Atoll, open Agents, create an agent for Gemini CLI and choose its project access.
- Copy the one-time
sk_atoll_...key, or the Gemini CLI setup snippet Atoll shows next to it. - Install the Atoll skill, save the key in a named CLI profile, verify the profile and check that Gemini CLI found the skill:
Shell / install the Atoll skill for Gemini CLI with a profile
npx --yes @atollhq/skill-gemini@latest --profile gemini-cli \
--key sk_atoll_... --org org-uuid --project project-uuid
npm exec --yes --ignore-scripts --package @atollhq/cli@latest -- \
atoll --profile gemini-cli auth status --json
gemini skills listThe installer copies the skill to ~/.gemini/skills/atoll/, adds a short routing hint to ~/.gemini/GEMINI.md and stores the key only in the gemini-cli profile. It does not write the key to your shell profile or select the profile globally. gemini skills list should show atoll as enabled. To install or refresh the skill without a key, run npx --yes @atollhq/skill-gemini@latest.
Tell Gemini which profile to use in the repository’s GEMINI.md. The file holds no secret, so you can commit it:
GEMINI.md / Atoll instructions for Gemini CLI
## Atoll
Use `atoll --profile gemini-cli` for Atoll. Start with
`atoll --profile gemini-cli heartbeat --json`. Comment your plan on the
issue before you change code, and link the pull request when it is open.Gemini CLI can then run the Atoll CLI. Install it once on the machine:
Shell / Atoll CLI with the Gemini CLI profile
npm install -g @atollhq/cli@latest
atoll --profile gemini-cli heartbeat --json
atoll --profile gemini-cli issue list --scope mine --json
atoll --profile gemini-cli issue get AP-123 --json
atoll --profile gemini-cli comment add AP-123 --body "Started. Plan: ..."
atoll --profile gemini-cli external-reference link --issue AP-123 \
--url https://github.com/acme/web/pull/42For scheduled or scripted runs, pass the prompt with gemini -p. Headless mode exits in an untrusted folder, so trust the repository first.
MCP 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. Gemini CLI hides inherited environment variables whose names contain KEY from MCP servers, so name both variables in the server’s env. Export ATOLL_API_KEY and ATOLL_ORG_ID before you start Gemini CLI; it expands $ATOLL_API_KEY from your shell, so the file still holds no secret:
settings.json / Atoll stdio server with an API key
{
"mcpServers": {
"atoll": {
"command": "npx",
"args": ["-y", "@atollhq/mcp-server", "--stdio"],
"env": {
"ATOLL_API_KEY": "$ATOLL_API_KEY",
"ATOLL_ORG_ID": "$ATOLL_ORG_ID"
}
}
}
}Use either the hosted entry or the stdio entry under the name atoll, not both.
Capabilities
What Gemini CLI can do in Atoll
Read context
Heartbeat, assigned issues, goals, KPIs, initiatives and project workflows, so Gemini 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, and the CLI guide lists every command.
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 gemini-cli 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 gemini-cli issue list --scope mine; atoll --profile gemini-cli 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 gemini-cli issue get AP-123 --json; atoll --profile gemini-cli comment list AP-123 --json |
| Start work | Move the issue to a status that exists on its board, so humans can see Gemini CLI has picked it up. | atoll_update_issue | atoll --profile gemini-cli 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 gemini-cli comment add AP-123 --body "..." |
| Link the pull request | Attach the PR Gemini CLI opened. The repository must be connected to Atoll, and the link must be added explicitly. | atoll_link_external_reference | atoll --profile gemini-cli 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 gemini-cli 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 Gemini CLI 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
Gemini CLI 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, Gemini CLI 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 Gemini CLI agent its own key, keep it out of the repository, GEMINI.md 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 Gemini CLI can do with atoll --profile gemini-cli agent-context --live-permissions or the atoll_get_auth_context tool. Details are in agent safety and permissions.
FAQ
Gemini CLI and Atoll questions
How do I add the Atoll MCP server to Gemini CLI?
In a folder you trust, run gemini mcp add --transport http atoll https://atollhq.com/mcp. Then start Gemini CLI, run /mcp auth atoll and sign in to Atoll in the browser. On the consent page, choose the agent profile Gemini CLI may use.
What does Gemini CLI project management look like in Atoll?
Gemini CLI gets its own agent member in your Atoll workspace. Humans assign it issues on the same board they use. Gemini 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 in your browser. Use @atollhq/skill-gemini with a CLI profile when you want a dedicated agent API key, scripted commands, JSON output or a machine without a browser. Many teams install both; the skill teaches Gemini how Atoll works, and MCP or the CLI performs the reads and writes.
Why does Gemini CLI list the Atoll server as disconnected?
Either the folder is not trusted or the server is not signed in yet. Gemini CLI does not connect MCP servers in an untrusted folder, including servers in your user settings. Trust the folder when Gemini CLI asks, or run /permissions to change it. Then run /mcp auth atoll to sign in.
Does Gemini CLI 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 Gemini CLI when an issue is assigned?
No. Assigning an issue adds it to the agent’s queue; it does not start a Gemini CLI session. You start Gemini CLI, or schedule it yourself, and it calls Atoll to read its heartbeat and report progress. The Atoll local runner currently runs Codex, not Gemini CLI.
References
Sources
Gemini CLI documentation checked 13 November 2026; commands tested with Gemini CLI 0.68.0. Google’s documentation says Gemini CLI was replaced by Antigravity CLI on 18 June 2026 for unpaid tier and Google One users, so check which CLI your team uses and Google’s current docs before you roll this out.