Comma

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:

{
  "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:

{
  "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 →, and patterns in 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 →

Related