The Comma MCP server

One scoped token. The agent ships the report, anchors comments, and replies to reviewers — under your control.

Comma exposes a Model Context Protocol server (Streamable HTTP transport) at https://commareports.com/api/mcp. It is the same surface as the REST API, exposed as typed tools so an agent in Claude Code, Cursor, or VS Code can collaborate on reports the way a human teammate would.

What an agent can do over MCP

Connect once. The agent gets:

The shape is deliberate, not minimal: the MCP server exposes the same report, comment, sharing, review, and automation primitives a human collaborator would reach for in the UI — so anything you can set up in Comma, an agent can set up through Claude. It still does not pretend to be a general AWS console or a code-execution sandbox.

Why MCP and not just an API

The REST API at /api/v1/* does the same things. MCP adds three properties that matter for an agent:

1. Typed tools instead of OpenAPI docs. The agent reads a small, purpose-built tool list and doesn't have to parse a full REST schema to know what a create_report call expects.
2. One install line. Attaching Comma to an editor is a single command, not a code change to the agent's prompt. The agent picks up the tools without modification.
3. One credential model. The same comma_sk_… token gates the REST API, the MCP server, and any routine that token created. Revoke once and the agent loses every surface in one motion.

One token, one revoke

Comma's auth model is intentionally narrow:

• REST API (/api/v1/*) — Authorization: Bearer comma_sk_…
• MCP server (/api/mcp) — same Bearer comma_sk_…, same scopes
• Routines — execute under the token that created them

If the token leaks — laptop lost, repo accidentally public, employee leaves — you revoke it once and the agent loses the REST API, the MCP server, and its routines simultaneously. There is no second credential to chase.

Tokens are scoped — both by capability (read reports, write reports, read or write comments, routines, connections, sharing) and by which reports they can touch — revocable (one click in Settings → API tokens), and rate-limited per token. A read-only token can fetch a report and its comments but can't publish it or stand up a routine; the same scope check applies identically to the REST API and every MCP tool.

How agents fit a Comma workflow

Anchored comments are the load-bearing primitive. Once the agent and the humans share a comment layer, the loop closes:

1. Agent posts a report. create_report lands HTML as a new artifact in the workspace.
2. Reviewers open the link. Same link-first sharing the rest of Comma uses. Reviewers leave anchored comments via the UI.
3. Agent reads the comments. list_comments pulls back the thread, including the selected text the comment is anchored to.
4. Agent replies or adjusts. Either reply_to_comment on the thread, or update_report to ship a new revision that addresses the feedback.
5. Reviewers resolve. set_comment_status if the agent wants to mark a thread closed.

Every action is recorded under the token. Revision history is intact. The human and the agent see the same surface.

Pairing MCP with routines

The MCP server is the on-demand surface — an agent acts in response to a human prompt. Routines are the scheduled surface — Comma re-runs an underlying skill on a cron and posts the HTML as a new revision without anyone asking.

You can pair them. A routine fires daily and posts the new revision. A human reviewer leaves an anchored comment. The next time the agent runs (either via routine or directly), it reads the comment via list_comments and adjusts.

Creating a routine is itself an MCP tool now: create_routine (plus create_skill and create_connector for the recipe and credentials it runs) so an agent can stand up the whole scheduled loop without leaving the conversation. The REST API and the Claude Code plugin's /comma-routine slash command do the same thing. The routine's runs interact with the same report and comment surface the MCP server exposes.

See Routines →.

Editor integrations

The MCP server speaks the standard Model Context Protocol. Any client that supports MCP can connect.

• Use Comma with Claude Code — comma plugin with slash commands (/comma-publish, /comma-search, /comma-routine, /comma-link) plus MCP attachment in one install.
• Use Comma with Cursor — direct MCP server configuration in Cursor's settings.
• VS Code — works with any VS Code extension that supports MCP servers.

The fastest install is the one-liner:

curl -fsSL https://commareports.com/install.sh | sh

(Windows: iwr https://commareports.com/install.ps1 -useb | iex.)

The deliberate scope

What MCP on Comma is for:

• Publishing HTML reports from an agent's run, and controlling who can see them.
• Reading and replying to anchored comments.
• Searching the workspace for a relevant report.
• Uploading attached assets.
• Standing up the automation around a report: reviewers, routines, the skills they run, the connectors they use, and the webhooks that fan events out.

What it is not for:

• Executing arbitrary code on Comma's infrastructure.
• Running queries against your warehouse — the skill does that on its own, using a connector you configured.
• Replacing your editor's existing tools — Comma is one collaborator among many.
• Posting to arbitrary third-party surfaces. Comma only delivers to the GitHub/Linear integrations and webhooks you explicitly connect.

The sharp scope is the point. Comma is a measuring instrument for HTML reports; the MCP server is that instrument exposed as agent tools.

Try it

The fastest test is a one-liner from a Claude Code or Cursor session — ask the agent to publish a Markdown-to-HTML report you have lying around, then leave an anchored comment on it from the web UI and ask the agent what it sees.

Install the plugin →

Related

• Use Comma with Claude Code
• Use Comma with Cursor
• Where should my AI agent post its work?
• Routines — hosted cron for AI skills