# Use Comma with Codex — publish HTML reports from your agent

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

> Attach the Comma MCP server to OpenAI Codex. Your Codex agent can publish HTML reports, search the workspace, and read and reply to anchored comments under a scoped token.

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

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

```bash
export COMMA_API_TOKEN=comma_sk_…
```

If your Codex version only supports stdio servers, bridge to the hosted
endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```toml
[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 →](/docs/api-tokens), and patterns in
[Scoped tokens for AI agents →](/agents/scoped-tokens-for-ai-agents).