Comma

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.

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

export COMMA_API_TOKEN=comma_sk_…

If your Gemini CLI version predates httpUrl, bridge to the hosted endpoint with mcp-remote as a stdio server:

{
  "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:

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 →, patterns in scoped tokens for AI agents →.

Related