Skip to content

Use the MCP server

This guide shows you how to connect an external MCP client — Claude Code, an editor, the MCP Inspector — to Control Center’s own tool server.

Control Center registers 110 tools and serves them over the Model Context Protocol at protocol version 2024-11-05. Whole tool families you might expect are absent: there are no meeting or calendar tools and no project tools.

The MCP surface shares the main cc_server listener. There is no separate MCP port.

Endpoint Method Purpose
/mcp POST Streamable HTTP transport — this is what a client speaks
/mcp DELETE End a session
/sse GET Server-sent notification stream

So a default local install is at http://127.0.0.1:9030/mcp.

  1. Go to Settings → Server → MCP servers
  2. Read the MCP server card — it shows running or stopped and the port it is listening on

The surface is on by default on a fresh install. Only the server owner sees the card’s token, and only they can start or stop the endpoint. Start on app launch controls whether it comes back after a restart; Start / Stop are session controls that do not change that preference.

The server binds loopback by default, so the endpoint is only reachable from the machine cc_server runs on unless you started it with --bind any.

Every request needs the server’s MCP token, from any machine, loopback included. The server creates it the first time it starts. There is no way to turn it off and no way to clear it.

  1. On Settings → Server → MCP servers, find the Authentication token row
  2. Press Show token and copy it
  3. To replace it, press Rotate token. The server switches to the new token at once, and every client still using the old one is refused until you give it the new one

Point your client at the Streamable HTTP endpoint and send the token as Authorization: Bearer <token> on every request, GET /sse included. There is no other way to send it: a token in the URL is not accepted. The exact configuration shape is your client’s business.

{
"mcpServers": {
"control-center": {
"type": "http",
"url": "http://127.0.0.1:9030/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}

Claude Code will not pick this up from a project .mcp.json — it gates project-scoped MCP servers behind an approval prompt that a non-interactive claude -p never answers. Pass the config explicitly:

Terminal window
claude --mcp-config /path/to/mcp.json --strict-mcp-config

--strict-mcp-config makes Claude use only that file, so the same server is not also discovered from the project and registered twice.

Checkpoint: ask the client to list its tools. You should see mcp__* entries covering tickets, spaces, memory, code graph and review.

The token opens every tool on the server, so the endpoint also refuses anything a web page could have sent, before it looks at the token:

Request Answer
An Origin header that is not a page on this machine (http://localhost, http://127.0.0.1 or http://[::1], any port) 403, “Cross-origin requests are not accepted”
A Host header that is neither this listener’s loopback address and port nor the server’s public host name 403, “Unknown host”
A POST whose body is not application/json 415
No token, or a wrong one 401

To serve MCP beyond the host, start the server with --bind any and send the token from the other machine, addressing the server by its public host name.

Every tool that touches workspace-scoped data requires workspace_id and a call without it is refused rather than resolved against some “current” workspace:

{
"workspace_id": "acme",
"title": "Fix login bug",
"priority": "high"
}

The id is the one in your browser or app URL: /workspaces/<workspace_id>/…. The only exemptions are tools that genuinely span workspaces, such as list_workspaces and the newsfeed tools — the newsfeed is per-user and an agent has no user of its own, so those tools operate on the server owner’s feeds.

Repo-scoped tools additionally check that the repo is linked to that workspace.

  • Mode gating. A call is resolved against the mode of the calling agent’s space, server-side. An agent in a read-only mode cannot reach a write tool by omitting space_id — the mode is looked up from its active run instead.
  • Action guardrails. Mutating tools declare their effect classes and go through the same policy the rest of the product uses. See Configure guardrails.
  • Confirmation. Some destructive tools build a confirmation payload that has to be approved before the call proceeds.

The full catalogue is advertised in tools/list with no discovery gating — an external MCP client refuses to call a tool that is not in its cached list, so hiding tools breaks them rather than tidying them.

This guide covers Control Center’s own endpoint. The other direction is the MCP servers that Control Center connects to and hands on to the agents it runs. You set those up under Settings → Server → MCP servers, at two levels. Either way, Control Center connects to the server itself and passes its tools on to the run, so the built-in harness and Claude Code receive the same tools and the same approval prompts. A Claude Code run sees them under the control-center server, as mcp__control-center__mcp__<server>__<tool>.

Workspace admins add these under Workspace MCP servers. Every agent run in the workspace receives their tools; runs in other workspaces do not.

  1. Select Add server and give it a short name: letters, digits, - and _, up to 24 characters. Tools appear as mcp__<name>__<tool>.
  2. Choose how to reach it:
    • Command (stdio): an executable and its arguments, plus any environment variables it requires.
    • URL (HTTP or SSE): the endpoint, plus any headers it requires, such as Authorization: Bearer ….
  3. Save. Checkpoint: the server shows Connected with a tool count.

Values for environment variables and headers are kept in the server’s secrets file and are never shown again. To change a value, replace it; to remove it, delete the name.

A command runs on the server’s machine as the server’s own user, so it doesn’t start until the server owner approves it. Until then, it shows Awaiting approval. A URL server works straight away, but until the server owner approves it, it can reach only public addresses. Approval also permits localhost and private networks. When the server owner saves a server, that counts as approval. If anyone else changes how a server starts or where it connects, it needs approval again. Switching a server on or off keeps its approval.

Personal servers belong to the server owner and are listed under External MCP servers. Servers configured on the server’s machine for Claude, Codex, Cursor, Gemini, VS Code, Windsurf, OpenCode or in a .mcp.json file are found there automatically. The server owner can also add their own with Add server, using the same form. A server you add takes precedence over a discovered one with the same name.

They act with the server owner’s identity and credentials:

  • They are available only in runs the server owner starts or is accountable for, including automation in a workspace the owner is accountable for. That covers built-in harness runs and Claude Code runs alike.
  • A member’s run, automation bound to a member, and every run on a server with no recorded owner receive none of them. There, the tools are not listed, cannot be called and do not appear in tool search.
  • Neither personal nor workspace servers are served to the MCP token or to paired devices, and their resources and prompts are not passed on.

Signing in to a server with OAuth isn’t available from the form. Use a server that accepts a token in a header, or configure it for one of the tools above, where it is discovered.

  • Check the MCP server card says running
  • Check the port matches your cc_server port
  • On Claude Code, check you passed --mcp-config and --strict-mcp-config

The request carried no token, or an old one. Copy the current token from the Authentication token row and send it as Authorization: Bearer <token>. A token in the URL is ignored.

The request carried an Origin from a web page, or a Host the server does not answer to. Call the endpoint from a client rather than a browser page, by the server’s loopback address or its public host name.

Send POST /mcp bodies as application/json.

A tool call fails with “Missing or invalid argument: workspace_id”

Section titled “A tool call fails with “Missing or invalid argument: workspace_id””

Add workspace_id. There is no implicit workspace.

MCP tools lists the catalogue. Call the name exactly as it appears there.