# Comma MCP Server — the agent-collaboration surface for HTML reports Canonical: https://commareports.com/mcp > Comma exposes a Model Context Protocol server so Claude Code, Cursor, and VS Code agents can publish reports, anchor comments, and reply to reviewers — under one scoped, revocable token. # 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](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: 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 →](/features/routines). --- ## Editor integrations The MCP server speaks the standard Model Context Protocol. Any client that supports MCP can connect. - **[Use Comma with Claude Code](/mcp/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](/mcp/cursor)** — one-click deeplink install, or direct MCP server configuration in Cursor's settings. - **[Use Comma with VS Code](/mcp/vscode)** — one `code --add-mcp` command, or a committable `.vscode/mcp.json` that prompts for the token. - **[Use Comma with Windsurf](/mcp/windsurf)** — a `serverUrl` entry in Cascade's `mcp_config.json`, with an `mcp-remote` fallback. The fastest install is the one-liner: ```bash 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 →](https://commareports.com/install.sh)** ## 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, and Claude Desktop. ### Related - [Use Comma with Claude Code](/mcp/claude-code) - [Use Comma with Cursor](/mcp/cursor) - [Use Comma with VS Code](/mcp/vscode) - [Use Comma with Windsurf](/mcp/windsurf) - [Where should my AI agent post its work?](/agents/where-should-my-agent-post) - [Routines — hosted cron for AI skills](/features/routines)