MCP Integration

CtxE exposes semantic code search and goal-driven Ask through the Model Context Protocol.

How it works

An MCP client launches ctxe mcp as a subprocess and exchanges JSON-RPC messages over stdin/stdout.

Use an absolute binary path when the client may not inherit your shell PATH.
The server exposes two tools, semantic_search and ask_context. Both are read-only and take the absolute path of the workspace being explored.
Indexing, readiness, chunk bodies and saved Ask records are CLI commands: ctxe index, ctxe status, ctxe fetch and ctxe records.
Server-backed indexing and Ask require a valid ctxe login session.

Installer setup

The official installer detects Claude and Codex installations and offers to configure CtxE. It writes the MCP command, allows the two CtxE tools, and installs the ctxe and ctxe-explore agent skills with a short pointer to them, without replacing unrelated client configuration.

curl -fsSL https://storage.ctxe.tlelabs.com/ctxe/latest/install.sh | sh

# Then fully restart the MCP client selected during installation.

Claude Code

If automatic setup was skipped, add an entry to ~/.claude.json. Prefer the absolute path returned by command -v ctxe:

{
  "mcpServers": {
    "ctxe": {
      "type": "stdio",
      "command": "/home/user/.local/bin/ctxe",
      "args": ["mcp"]
    }
  }
}

The installer also allows mcp__ctxe__semantic_search and mcp__ctxe__ask_context in ~/.claude/settings.json, installs the skills under ~/.claude/skills, and adds a skill pointer to ~/.claude/CLAUDE.md.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.ctxe]
command = "/home/user/.local/bin/ctxe"
args = ["mcp"]

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ctxe": {
      "command": "/home/user/.local/bin/ctxe",
      "args": ["mcp"]
    }
  }
}

VS Code

Add to your MCP settings or .vscode/mcp.json:

{
  "servers": {
    "ctxe": {
      "type": "stdio",
      "command": "/home/user/.local/bin/ctxe",
      "args": ["mcp"]
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "ctxe": {
      "command": "/home/user/.local/bin/ctxe",
      "args": ["mcp"]
    }
  }
}

Other MCP clients

Transport: stdio
Command: the absolute path to ctxe
Arguments: ["mcp"]
Working directory: optional; every workspace-aware request carries an explicit path

Tools

Tool	Purpose
`semantic_search`	Find the code for a behavior you cannot name yet, ranked across up to four phrasings of the request
`ask_context`	Explain how something works across files, with a synthesized answer and evidence chunk IDs

See Tools Reference for request parameters, defaults, and examples.

Earlier releases exposed more tools and let [mcp].exposed_tools and expose_experimental_tools narrow them. Both settings are retired: the server warns about them at startup and ignores them, and ctxe config set rejects them.

Recommended workflow

Run ctxe status on the active project.
If it is not indexed, get user approval and run ctxe index.
Call semantic_search to locate the code for each thing the task touches.
Call ask_context when the change depends on how that code works across files.
Read chunk bodies with ctxe fetch, using IDs returned for the same workspace.

Troubleshooting

Tools do not appear

Run ctxe mcp in a terminal and confirm it stays running without startup errors.
Use the binary's absolute path in client configuration.
Fully restart the MCP client after editing configuration.

Authentication required

ctxe whoami
ctxe login

Client configuration does not use third-party embedding API keys. Authentication is the browser-based CTXE Server session.

Workspace is not indexed

ctxe index /path/to/project
ctxe status /path/to/project

Indexing is a CLI step; an agent should ask before running ctxe index.