Copy as MD MD

MCP Integration

CtxE exposes its full search and navigation capabilities via the Model Context Protocol (MCP). This lets AI assistants query your codebase context in real time.

How it works

CtxE runs as an MCP server over stdio transport. The AI client spawns ctxe mcp as a subprocess and communicates via JSON-RPC over stdin/stdout.

All tools are read-only (except index_workspace) and operate on the workspace path you provide with each call.

Claude Code (auto-configured)

The install script automatically configures CtxE for Claude Code. After installation, restart Claude Code and the tools are available immediately.

What the installer does:

1. Adds MCP server entry to ~/.claude.json
2. Allows tool permissions in ~/.claude/settings.json
3. Adds usage guidance to ~/.claude/CLAUDE.md

The resulting config in ~/.claude.json:

{
  "mcpServers": {
    "ctxe": {
      "type": "stdio",
      "command": "/path/to/ctxe",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ctxe": {
      "command": "ctxe",
      "args": ["mcp"]
    }
  }
}

Restart Cursor after adding the config.

VS Code

Add to your VS Code MCP config (settings or .vscode/mcp.json):

{
  "servers": {
    "ctxe": {
      "command": "ctxe",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.ctxe]
command = "ctxe"
args = ["mcp"]
enabled = true

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ctxe": {
      "command": "ctxe",
      "args": ["mcp"]
    }
  }
}

Other MCP clients

Any MCP-compatible client that supports stdio transport can use CtxE. The general pattern:

• Transport: stdio
• Command: ctxe (or full path to binary)
• Args: ["mcp"]

Exposed tools

By default, CtxE exposes 10 stable tools to MCP clients:

See Tools Reference for detailed documentation on each tool.

Example prompts

Once CtxE is connected, you can ask your AI assistant questions like:

• • "How does the authentication flow work in this project?"
• • "What would break if I change the signature of UserService.create()?"
• • "Find all implementations of the Repository trait"
• • "Which files handle payment processing and what are their dependencies?"
• • "Show me the call graph for handle_request() — who calls it and what does it call?"

The AI will automatically use the right CtxE tools (ask_context, find_callers, etc.) based on your question.

Configuration

MCP behavior is controlled via the [mcp] section in your config file:

# ~/.ctxe/config.toml

[mcp]
# Expose experimental tools (default: false)
expose_experimental_tools = false

# Explicitly list which tools to expose (order matters for client display)
# Default: all stable tools. Use ["*"] to expose everything.
# exposed_tools = ["ask_context", "get_status", "fetch_chunks"]

Troubleshooting

Tools not showing up

• Verify ctxe mcp runs without error in your terminal
• Ensure the binary is in your PATH, or use the full absolute path in config
• Restart your AI client after modifying the config

Workspace not indexed

If get_status shows the workspace is not ready, index it first:

ctxe index /path/to/your/project

Or ask the AI to run index_workspace via MCP — it will handle it automatically.

Permission denied (Claude Code)

If Claude Code prompts for permission on each tool call, the installer may not have added permissions correctly. Check ~/.claude/settings.json contains the tool entries:

{
  "permissions": {
    "allow": [
      "mcp__ctxe__ask_context",
      "mcp__ctxe__get_status",
      "mcp__ctxe__fetch_chunks",
      ...
    ]
  }
}

Embedding API key not configured

If indexing fails with an API error, ensure your Voyage AI key is set in the config:

# ~/.ctxe/config.toml

[providers.voyage]
api_key = "your-voyage-api-key"

The install script prompts for this during setup. You can also set it via environment variable VOYAGE_API_KEY.