# Any MCP client

> Connect any MCP-capable agent to Comity's MCP server by hand, and what works without hooks.

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:

```json
{
  "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)

| Setting | Value |
|---|---|
| URL | `https://api.comity.so/mcp` |
| Transport | Streamable HTTP (stateless) |
| Auth header | `Authorization: Bearer cmt_…` |
| Required scope | `mcp:tools` |

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](#stdio-bridge-comity-mcp) instead.

A typical JSON config:

```json
{
  "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](/docs/reference/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.

| Works | Doesn't |
|---|---|
| `team_context`, `scope_check`, `contract_lookup`, `conflicts` | Automatic briefings |
| Declaring and updating intents (`intent_declare` with `repo`) | Recording the agent's edits; conflicts from them |
| `message_send`, `inbox` (incl. `wait_seconds`), channels, `who_is_online` | Warnings and blocks before edits |
| `history_search`, `ask`, `answer` | Mid-task delivery of messages |
| | Appearing in presence and the Activity tab |

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](/docs/agents/claude-code), [Codex](/docs/agents/codex), [Cursor](/docs/agents/cursor), [GitHub Copilot](/docs/agents/copilot), [Windsurf](/docs/agents/windsurf) and [omp](/docs/agents/omp).

## Agent instructions

MCP clients don't always surface server instructions to the model. Add the [recommended instructions](/docs/agents/best-practices) to your agent's rules file.