# Use Comma with Windsurf — publish HTML reports from Cascade

Canonical: https://commareports.com/mcp/windsurf

> Add the Comma MCP server to Windsurf's mcp_config.json and Cascade can publish HTML reports, search the workspace, and read and reply to anchored comments under a scoped token.

# Use Comma with Windsurf

Windsurf's Cascade agent speaks the Model Context Protocol. Attach Comma's
hosted MCP server and Cascade picks up the full set of report and comment
tools — same scoped token shape as the REST API.

## Add Comma to Windsurf

Windsurf reads MCP servers from `~/.codeium/windsurf/mcp_config.json`
(also reachable through the MCP section of Windsurf's settings UI —
naming and menus have shifted between releases, so go by the file if in
doubt). Add a Comma entry pointing at the hosted endpoint:

```json
{
  "mcpServers": {
    "comma": {
      "serverUrl": "https://commareports.com/api/mcp",
      "headers": {
        "Authorization": "Bearer comma_sk_…"
      }
    }
  }
}
```

Replace `comma_sk_…` with a token from
**Settings → API tokens → New token** on Comma. Scope it to the actions
you want the agent to take — typically `reports:write` and
`comments:write`. Then reload Windsurf (or refresh its MCP servers) so
Cascade picks up the tools.

Windsurf's support for remote HTTP servers has evolved across versions.
If your version only handles stdio servers, or the `serverUrl` entry
doesn't connect, bridge to the hosted endpoint with
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "comma": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://commareports.com/api/mcp",
        "--header",
        "Authorization: Bearer comma_sk_…"
      ]
    }
  }
}
```

Same endpoint, same token — the bridge just speaks stdio to Windsurf and
HTTP to Comma.

## 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`        |

Cascade picks the right tool from its reasoning — there are no
Windsurf-specific commands to memorize.

## Common workflows

### Publish at the end of a task

Ask Cascade to "summarize this migration as an HTML report and publish it
to Comma." The agent generates the HTML, calls `create_report`, and hands
back the share link — your team opens a document, not an editor session.

### Respond to review feedback

Teammates leave anchored comments on the published report. Next session,
ask Cascade to "check the comments on the migration report and address
them" — it reads the threads with `list_comments`, ships a new revision
with `update_report` (same URL), replies, and resolves the threads.

### Keep one URL across agents

Reports belong to your workspace, not to the agent that wrote them. A
report Cascade published can be updated by Claude Code or Cursor tomorrow
— the link your stakeholders bookmarked keeps working.

## Token shape

- Lives in `~/.codeium/windsurf/mcp_config.json` — a user-level file, so
  it won't end up committed with a project repo, but treat it like any
  API key on a shared machine.
- Scoped — you choose which actions it can take when you create it.
- Revocable in one click from **Settings → API tokens**. Revocation
  applies immediately to the REST API, the MCP server, and any routines
  the token created.
- Rate-limited per token (60 requests/minute by default).

Details in [API tokens →](/docs/api-tokens), and patterns in
[Scoped tokens for AI agents →](/agents/scoped-tokens-for-ai-agents).

## Try it

Drop the snippet into `mcp_config.json`, generate a token, reload
Windsurf, and ask Cascade to publish anything you have lying around as
HTML. From the web UI, leave an anchored comment and ask the agent what
it sees on its next turn.

**[Generate a token →](https://commareports.com/settings/tokens)**

### Related

- [Comma MCP server overview](/mcp)
- [Use Comma with Cursor](/mcp/cursor)
- [Use Comma with VS Code](/mcp/vscode)
- [Where should my AI agent post its work?](/agents/where-should-my-agent-post)