Local MCP Setup

Connect your agent to CTX.

GitHub Pages is static. The CTX MCP server runs locally on your machine through an MCP-capable agent or IDE. Choose your platform, set the repository path, and copy the configuration for your agent.

Back to docs Full MCP guide Download release

Step 1

Set local paths

Install root CTX repository Mode

Keep read-only mode for first connection. A successful setup should let the agent call ctx_plan and report branch, dirty state, next work, context, and runbook guidance.

Verify install

Run this first to confirm the MCP launcher exists.

Generic MCP JSON

Use this shape for MCP clients that accept an mcpServers block with explicit type and tool exposure.

Smoke test prompt

Paste this into the agent after restarting it.

Use the ctx MCP server. Call ctx_plan with purpose "mcp-local-smoke-test". Report branch, dirty state, recommended task, context packet id, and runbook suggestions.

Step 2

Choose your agent

Recommended

Claude setup in three steps

Copy the Claude Code command or Claude Desktop JSON below.
Restart Claude so it loads the local MCP server.
Paste the smoke test prompt and confirm Claude can call ctx_plan.

Use read-only first. Switch to write only when you want Claude to create or update CTX artifacts in the selected repository.

Claude Code

Run this once from a terminal. Claude Code will register CTX as a local MCP server named ctx.

Claude Desktop

Paste this into the Claude Desktop MCP configuration file, then restart the app.

Claude project config

For project-scoped Claude Code setup, save this as .mcp.json in the repository root.

Claude smoke test

After restarting Claude, paste this to verify CTX tools are available.

VS Code / Copilot

Copies the VS Code servers configuration shape.

Codex

Copies a config.toml block for Codex MCP startup.