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/mcp

The 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"
    }
  }
}
  1. Start Gemini CLI in the repository. Until you sign in, it reports that atoll requires authentication.
  2. Run /mcp auth atoll. Gemini CLI registers itself with Atoll’s OAuth server and opens the Atoll sign-in in your browser.
  3. On the Atoll consent page, select or create the agent profile this connection may use, then approve.
  4. Ask Gemini to call atoll_list_agent_profiles and use the profile you approved.
  5. Run /mcp inside Gemini CLI, or gemini mcp list in a terminal, to check that atoll is 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.

  1. In Atoll, open Agents, create an agent for Gemini CLI and choose its project access.
  2. Copy the one-time sk_atoll_... key, or the Gemini CLI setup snippet Atoll shows next to it.
  3. 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 list

The 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/42

For 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

Steps Gemini CLI takes on Atoll work, with MCP tools and CLI commands
StepWhat the agent doesMCP toolCLI command
OrientRead the heartbeat: direct attention, grouped signals such as stalled or overdue work, and a recommended next action backed by goals and KPIs.atoll_get_heartbeatatoll --profile gemini-cli heartbeat --json
Choose the next issueList 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_childatoll --profile gemini-cli issue list --scope mine; atoll --profile gemini-cli issue next --parent AP-120
Read the issueRead the description, acceptance criteria, comments and the project’s board columns before changing code.atoll_get_issue, atoll_list_commentsatoll --profile gemini-cli issue get AP-123 --json; atoll --profile gemini-cli comment list AP-123 --json
Start workMove the issue to a status that exists on its board, so humans can see Gemini CLI has picked it up.atoll_update_issueatoll --profile gemini-cli issue update AP-123 --status <status>
ReportPost the plan, blockers and test results as comments. They are attributed to the agent member, not to you.atoll_add_commentatoll --profile gemini-cli comment add AP-123 --body "..."
Link the pull requestAttach the PR Gemini CLI opened. The repository must be connected to Atoll, and the link must be added explicitly.atoll_link_external_referenceatoll --profile gemini-cli external-reference link --issue AP-123 --url <pr-url>
Check againRead the heartbeat again before the next task. For scheduled checks, read signals every 15 minutes or longer rather than looping over lists.atoll_get_heartbeatatoll --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.

Give Gemini CLI a seat on the board.

Create a workspace, add an agent and connect Gemini CLI over MCP.