Any MCP client

Any agent that supports MCP servers can use Comity's tools: Gemini CLI, Windsurf, Cline, OpenCode, Amp and others. If comity init doesn't configure yours, add the server yourself. The simplest way is the stdio bridge, which needs only comity login and no token in any config file.

Stdio bridge: comity mcp

comity mcp is a local stdio MCP server. It forwards every request to Comity with the token comity login stored (COMITY_TOKEN and COMITY_SERVER override it) and streams the answers back. Nothing secret goes into the client's config, so the config is safe to commit to a repo.

Use the entry comity init writes. node starts comity mcp through the system shell, so the same entry works for every teammate on Windows, macOS and Linux (npm installs comity on Windows as a comity.cmd script, which many clients can't start directly). Node must be on PATH, as it already is wherever the CLI is installed:

{
  "mcpServers": {
    "comity": {
      "command": "node",
      "args": ["-e", "const c=require('child_process').spawn('comity '+process.argv.slice(1).join(' '),{stdio:'inherit',shell:true});c.on('error',()=>process.exit(1));c.on('exit',(k)=>process.exit(k===null?1:k))", "mcp"]
    }
  }
}

If you're not logged in, the client's connection fails with "not logged in. Run comity login…". Run comity login, then restart the MCP server in your client. To see each request the bridge forwards on stderr (your client's MCP log), set COMITY_DEBUG=1 in the server's env.

Remote server (Streamable HTTP)

Use your personal token: the one comity login stored (comity auth-header prints Bearer cmt_…, comity mcp-headers the JSON header). Read it from an environment variable rather than pasting it into a config file, and never commit it. If your client starts outside a shell where COMITY_TOKEN is set, use the stdio bridge instead.

A typical JSON config:

{
  "mcpServers": {
    "comity": {
      "url": "https://api.comity.so/mcp",
      "headers": { "Authorization": "Bearer ${COMITY_TOKEN}" }
    }
  }
}

The exact key names and variable syntax differ per client (httpUrl, serverUrl, ${env:COMITY_TOKEN}, …); check your client's MCP docs. If your client can run a command to produce headers, use comity mcp-headers (prints {"Authorization":"Bearer cmt_…"}) or comity auth-header (prints Bearer cmt_…).

Check it with the client's MCP listing: it should show 17 tools, from team_context to answer. See MCP tools.

What works without hooks

Hooks are what make Comity automatic: briefings at session start and on each prompt, edits recorded and analyzed, warnings and blocks before edits, messages delivered mid-task. With MCP alone, none of that happens; the agent only gets what it asks for.

Without a hooked session, tools can't infer the repo: pass repo (owner/name) to team_context, intent_declare, scope_check and contract_lookup. A declared intent's scope still takes part in conflict detection, so teammates' agents see it.

The full integration (hooks plus MCP) is available for Claude Code, Codex, Cursor, GitHub Copilot, Windsurf and omp.

Agent instructions

MCP clients don't always surface server instructions to the model. Add the recommended instructions to your agent's rules file.