# Use Comma with Gemini CLI — publish HTML reports from your agent

Canonical: https://commareports.com/mcp/gemini-cli
Published: 2026-09-02

> Attach the Comma MCP server to Gemini CLI. Your agent can publish HTML reports, search the workspace, and read and reply to anchored comments under a scoped token.

# Use Comma with Gemini CLI

Gemini CLI speaks the Model Context Protocol. Attach Comma's hosted MCP server
and the agent gains the full set of report and comment tools — the same scoped
token shape as the REST API, with nothing to run locally.

## Add Comma to Gemini CLI

Gemini CLI reads MCP servers from the `mcpServers` object in its settings
file: `~/.gemini/settings.json` to make it available everywhere, or
`.gemini/settings.json` inside a repository to scope it to that project.

```json
{
  "mcpServers": {
    "comma": {
      "httpUrl": "https://commareports.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${COMMA_API_TOKEN}"
      }
    }
  }
}
```

```bash
export COMMA_API_TOKEN=comma_sk_…
```

If your Gemini CLI version predates `httpUrl`, bridge to the hosted endpoint
with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio
server:

```json
{
  "mcpServers": {
    "comma": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://commareports.com/api/mcp",
        "--header",
        "Authorization: Bearer ${COMMA_API_TOKEN}"
      ]
    }
  }
}
```

Mint the token at **Settings → API tokens → New token** on Comma and scope it
to what the agent should be able to do — usually `reports:write` and
`comments:write`. Restart the CLI; `/mcp` lists the Comma tools.

## What the agent can do

| Capability                | Tools                                                                    |
| ------------------------- | ------------------------------------------------------------------------ |
| Publish a report          | `create_report`, `update_report`                                         |
| Find existing reports     | `list_reports`, `search_reports`, `get_report`, `read_report`            |
| Leave / reply to comments | `add_comment`, `reply_to_comment`, `set_comment_status`, `list_comments` |
| Request review            | `request_review`                                                         |
| Manage assets             | `upload_report_asset`, `list_report_assets`, `delete_report_asset`       |

## Common workflows

### End a task with a link, not a transcript

Ask Gemini to "write this up as HTML and publish it to Comma." The agent
generates the document, publishes it, and hands back the URL — your reader
opens a styled page instead of scrolling a terminal.

### Put the rule in `GEMINI.md`

Gemini CLI reads project context from `GEMINI.md`. Writing the convention down
there means you stop asking for it:

```md
When you finish work a human needs to read, publish it to Comma as an HTML
report and reply with the URL. Update report `rep_xxxxxxxx` rather than
creating a new one.
```

### Address review feedback

Teammates leave anchored comments on the published report. Next session, ask
Gemini to "check the comments and address them" — it reads the threads, updates
the report at the same URL, replies, and resolves them.

## Why a scoped token matters

The token is the entire blast radius: it can carry as little as
`reports:write`, it can expire, and revoking it at **Settings → API tokens**
cuts the agent off everywhere — MCP and REST — in one motion. Details in
[API tokens →](/docs/api-tokens), patterns in
[scoped tokens for AI agents →](/agents/scoped-tokens-for-ai-agents).

### Related

- [MCP setup for every client](/mcp) · [Codex](/mcp/codex) ·
  [Cursor](/mcp/cursor) · [Claude Code](/mcp/claude-code)
- [Where should my agent post?](/agents/where-should-my-agent-post)
- [Let an agent respond to comments](/agents/let-an-agent-respond-to-comments)