MCP Client Setup

Ctxo speaks MCP over stdio. Every major coding client supports stdio MCP servers, usually via a JSON config file. The command is always the same:

ctxo mcp

What differs is where each client expects the config and what field names it uses.

One server, many clients

You can register Ctxo in multiple clients simultaneously. They each spawn their own Ctxo process against the same on-disk index.

Claude Code

Create .mcp.json in your repo root (committed, so your whole team shares the config):

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

Optional debug logging to stderr:

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"],
      "env": { "DEBUG": "ctxo:*" }
    }
  }
}

See Claude Code integration for per-project vs per-user config and hook-based index refresh.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

Restart Cursor. Ctxo tools appear under the MCP panel.

See Cursor integration for more.

GitHub Copilot

Copilot Chat (VS Code) reads MCP config from .vscode/mcp.json:

{
  "servers": {
    "ctxo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

Field names differ

Copilot uses servers (not mcpServers) and requires an explicit "type": "stdio". Claude Code / Cursor / Windsurf use mcpServers without a type field.

See Copilot integration for more.

Windsurf

Windsurf reads from ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

See Windsurf integration for more.

Cline

Cline (VS Code extension) reads cline_mcp_settings.json from its extension storage. Use the MCP Servers panel in the Cline UI, or edit the file directly:

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

See Cline integration for more.

Gemini CLI

Gemini CLI reads MCP servers from .gemini/settings.json (per-project) or ~/.gemini/settings.json (global). Use the same mcpServers schema as Claude Code and Cursor:

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

Project-level rules live in GEMINI.md at the repo root - ctxo init appends a marked section there. Restart gemini after editing.

Continue

Continue keeps each MCP server in its own JSON (or YAML) file under .continue/mcpServers/. Create .continue/mcpServers/ctxo.json:

{
  "mcpServers": {
    "ctxo": {
      "command": "npx",
      "args": ["-y", "@ctxo/cli"]
    }
  }
}

One file per server

Unlike Cursor / Claude Code where one config holds every server, Continue picks up each .continue/mcpServers/*.json file separately. To add another MCP server, drop another file next to ctxo.json rather than appending to it.

Project rules go to .continue/rules/ctxo.md. Reload Continue from the VS Code command palette after the install.

Using a pinned binary instead of npx

For tighter reproducibility (CI, shared dev containers), skip npx and point at the installed binary:

{
  "mcpServers": {
    "ctxo": {
      "command": "node",
      "args": ["./node_modules/@ctxo/cli/dist/index.js", "mcp"]
    }
  }
}

This avoids network resolution on every client start.

Verifying the connection

After restarting your client:

1. Confirm ctxo shows up as a connected MCP server.
2. Confirm 14 tools are listed (get_logic_slice, get_blast_radius, ...).
3. Confirm 1 resource is exposed: ctxo://status.
4. In your agent, ask: "Call ctxo://status and show me the result."

If tools are missing, check the client's MCP logs. Common issues:

Symptom	Fix
command not found: npx	Install Node.js >= 20 and restart the client
Server starts then exits	Run ctxo mcp in a terminal to see the real error
No index loaded	Run ctxo index in the repo root
Stale results	ctxo index or start ctxo watch

Next steps

• MCP Tools Overview - the 14 tools in detail
• Quick Start - end-to-end walkthrough