Use CoCo through MCP

Connect an assistant or application to inspect your workspaces, read agent updates, and optionally send instructions. CoCo provides an MCP (Model Context Protocol) server so compatible applications can use these tools.

Before you begin

Start cocod in one terminal:

cocod

Then register the repository from another terminal if you have not already:

coco repo add /absolute/path/to/project

Use an absolute repository path in MCP configuration so behavior does not depend on the directory from which the host starts.

Configure an MCP host

Set the server command to coco-mcp and pass the repository as arguments. A typical JSON-based host entry looks like this:

{
  "mcpServers": {
    "coco": {
      "command": "coco-mcp",
      "args": ["--repository", "/absolute/path/to/project"]
    }
  }
}

Hosts use different configuration filenames and sometimes different outer keys, but the command and argument list stay the same.

Configure Codex as the host

For Codex, add a standard input/output server to ~/.codex/config.toml:

[mcp_servers.coco]
command = "coco-mcp"
args = ["--repository", "/absolute/path/to/project"]

The equivalent standalone command is:

coco mcp serve --repository /absolute/path/to/project

Available tools

The repository is fixed when the server starts. By default it offers only read-only tools:

Tool	What it does
`workspaces.list`	List workspaces in the repository
`workspaces.status`	Show the current state of one workspace
`workspaces.diff`	Show changes made by one workspace
`signals.types`	Discover signal definitions and permissions
`signals.list`	Read retained updates from agents

Read-only does not mean content-free: the connected host can see workspace metadata, repository paths, diffs, and saved signal payloads. Enable the server only in hosts you trust with that information.

Allow messages

Add --allow-send only when the MCP host should be allowed to start another Codex turn:

{
  "mcpServers": {
    "coco": {
      "command": "coco-mcp",
      "args": ["--repository", "/absolute/path/to/project", "--allow-send"]
    }
  }
}

This adds workspaces.send. Any connected host can then start the first or a later turn under that workspace’s Codex permissions and account usage. Leave it disabled unless that is the access you intend to grant.

What this integration controls

To let a Codex workspace publish structured updates, select schema files with --signal-catalog DIR and grant specific versions with --allow-emit NAME@VERSION. See Publish agent updates for setup and Signal reference for publication permissions.

This MCP server lets another application control existing CoCo workspaces. Configure tools that should be available inside a Codex workspace through its selected Codex profile; that is a separate setting from the tools coco-mcp exposes to its host.