Comma

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:

Tool What it does
create_report Publish a new HTML report to your workspace
update_report Replace the report's HTML with a new revision
get_report / read_report Fetch an existing report's content and metadata
list_reports / search_reports Find reports by name, owner, or search term
add_comment Pin an anchored comment on a paragraph or table cell
reply_to_comment Continue an existing thread
set_comment_status Mark a thread resolved or reopened
list_comments Read what reviewers have said
request_review Notify named reviewers that the report is ready
upload_report_asset / list_report_assets / delete_report_asset Manage attached images and assets

The shape is deliberately narrow. The MCP server exposes the report and comment primitives — the same things a human collaborator would use the UI for. It 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 (which reports they can touch), revocable (one click in Settings → API tokens), and rate-limited per token.

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.

Today, creating a routine itself happens through the REST API or the Claude Code plugin's /comma-routine slash command rather than through an MCP tool. 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.
  • Reading and replying to anchored comments.
  • Searching the workspace for a relevant report.
  • Uploading attached assets.

What it is not for:

  • Executing arbitrary code on Comma's infrastructure.
  • Running queries against your warehouse — the skill does that on its own.
  • Replacing your editor's existing tools — Comma is one collaborator among many.
  • Posting to surfaces Comma doesn't own (Slack, email, GitHub).

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