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 |
set_report_sharing |
Publish or unpublish a report and set link access |
list_reviewers / create_reviewer / update_reviewer / delete_reviewer |
Configure the agent-reviewers that auto-comment on revisions |
list_routines / create_routine / update_routine / delete_routine / run_routine |
Schedule and run recurring work on a report |
list_skills / create_skill / delete_skill |
Author the reusable recipes a routine runs |
list_connectors / create_connector / delete_connector |
Store encrypted credentials a skill can use |
list_integrations / connect_integration / disconnect_integration |
Link GitHub / Linear so Comma can post report links |
list_notifications / create_notification / delete_notification |
Route report events to a Slack/Discord/plain webhook |
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:
- 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.
- 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.
- 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:
- Agent posts a report.
create_report lands HTML as a new artifact in
the workspace.
- Reviewers open the link. Same link-first sharing the rest of Comma
uses. Reviewers leave anchored comments via the UI.
- Agent reads the comments.
list_comments pulls back the thread,
including the selected text the comment is anchored to.
- Agent replies or adjusts. Either
reply_to_comment on the thread, or
update_report to ship a new revision that addresses the feedback.
- 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 — one-click deeplink install, or
direct MCP server configuration in Cursor's settings.
- Use Comma with VS Code — one
code --add-mcp command,
or a committable .vscode/mcp.json that prompts for the token.
- Use Comma with Windsurf — a
serverUrl entry in
Cascade's mcp_config.json, with an mcp-remote fallback.
- Use Comma with Codex — an
[mcp_servers.comma] block in
~/.codex/config.toml.
- Use Comma with Gemini CLI — an
httpUrl entry in
~/.gemini/settings.json.
- Use Comma with Claude Desktop — for the people on
your team who never open an editor.
- Use Comma with Cline — a
streamableHttp entry in Cline's MCP settings.
- Use Comma with Roo Code — a
streamable-http entry, global or in .roo/mcp.json.
- Use Comma with Continue — a
config.yaml block with the header under requestOptions.
- Use Comma with GitHub Copilot CLI — one
copilot mcp add --transport http command.
- Use Comma with Visual Studio — a
servers entry in .mcp.json for Copilot agent mode.
- Use Comma with JetBrains AI Assistant — IntelliJ, PyCharm and friends, via the
mcp-remote bridge.
- Use Comma with Junie — a
url + headers entry in ~/.junie/mcp/mcp.json.
- Use Comma with Zed — a remote entry under
context_servers.
- Use Comma with Kiro — a
url entry in ~/.kiro/settings/mcp.json.
- Use Comma with Amp — an
amp.mcpServers entry in Amp's settings.
- Use Comma with OpenCode — a
type: "remote" entry in opencode.json.
- Use Comma with Goose — a Streamable HTTP extension via
goose configure.
- Use Comma with Warp — Settings → Agents → MCP servers, or
~/.warp/.mcp.json.
- Use Comma with Augment Code — one
auggie mcp add --transport http command.
- Use Comma with Factory Droid —
droid mcp add --type http --no-oauth.
- Use Comma with Qwen Code —
qwen mcp add --transport http, or an httpUrl entry.
- Use Comma with LM Studio — a remote entry in LM Studio's
mcp.json, for local models.
The fastest install, for Claude Code, is the one-liner:
curl -fsSL https://commareports.com/install.sh | bash
(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 →
FAQ
What is the Comma MCP server? A hosted MCP server (Streamable HTTP)
at https://commareports.com/api/mcp — the REST API surface exposed as
typed tools for agents.
How does auth work? One scoped comma_sk_… Bearer token across REST,
MCP, and routines. Revoke once, the agent is out everywhere.
Why MCP over REST? Typed tools, one-line editor attachment, one
credential model. Same surface underneath.
What can't an agent do? Execute code on Comma, query your warehouse,
or post to surfaces you haven't explicitly connected.
Which clients connect? Any MCP-capable client — setup guides cover
Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, and Claude Desktop.
Related