Comma

Use Comma with Codex

Codex speaks the Model Context Protocol. Attach Comma's hosted MCP server and the agent picks up the full set of report and comment tools — same scoped token shape as the REST API, nothing to run locally.

Add Comma to Codex

Codex reads MCP servers from ~/.codex/config.toml. Add a Comma entry pointing at the hosted endpoint:

[mcp_servers.comma]
url = "https://commareports.com/api/mcp"
bearer_token_env_var = "COMMA_API_TOKEN"

export COMMA_API_TOKEN=comma_sk_…

If your Codex version only supports stdio servers, bridge to the hosted endpoint with mcp-remote:

[mcp_servers.comma]
command = "npx"
args = [
  "-y", "mcp-remote",
  "https://commareports.com/api/mcp",
  "--header", "Authorization: Bearer ${COMMA_API_TOKEN}",
]

Mint the token at Settings → API tokens → New token on Comma. Scope it to what the agent should be able to do — typically reports:write and comments:write.

Restart Codex. The agent now sees the Comma tools.

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

Common workflows

Publish at the end of a task

Ask Codex to "write up the migration plan as HTML 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 a terminal.

Respond to review feedback

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

Keep one URL across agents

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

Why a scoped token matters

The token is the entire blast radius: it can carry as little as reports:write, it can expire, and revoking it at Settings → API tokens cuts off the agent everywhere (MCP and REST) in one motion. Details in API tokens →, and patterns in Scoped tokens for AI agents →.