MCP Integration

CtxE exposes code search, graph navigation, workspace records, 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.
Most tools require the absolute current workspace path. list_workspaces is the no-argument exception.
index_workspace updates local index state. The other 15 public tools are read-only.
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, refreshes the current 16-tool permission list, and adds usage guidance without replacing unrelated client configuration.

curl -fsSL https://storage.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 updates CtxE-owned entries in ~/.claude/settings.json and the marked guidance section in ~/.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

Current public tools

The default public registry contains 16 stable tools:

Tool	Category	Purpose
`ask_context`	Agentic	Multi-round retrieval and synthesized evidence
`get_status`	System	Index state, counts, and capability health
`list_workspaces`	System	Accepted catalog ledger with desired watch state
`index_workspace`	Job	Incremental or forced workspace indexing
`fetch_chunks`	Retrieval	Read chunks by IDs returned from earlier calls
`find_definitions`	Retrieval	Resolve symbol definitions
`find_usages`	Graph	Find callers, implementations, imports, and other usages
`graph_neighbors`	Graph	Direct graph neighbors of one chunk
`graph_expand`	Graph	Config-bounded multi-hop expansion
`graph_paths`	Graph	Paths between two chunks
`get_impact`	Graph	Transitive dependents of a chunk
`get_workspace_tree`	File	Paginated indexed workspace tree
`inspect_path`	File	Browse or rerank chunks under a relative path
`get_record`	Record	Retrieve a workspace record by ID
`list_records`	Record	Filter and paginate workspace records
`search_records`	Record	Full-text record search

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

Tool filtering

An omitted or empty exposed_tools list exposes the full public registry. A non-empty list narrows tools in the order supplied. Use ["*"] to explicitly select all public tools.

# ~/.ctxe/config.toml
[mcp]
expose_experimental_tools = false
exposed_tools = ["ask_context", "get_status", "fetch_chunks", "find_definitions"]

Recommended workflow

Call get_status with the active project's absolute path.
If no usable index exists, get user approval and call index_workspace.
Use ask_context first for architecture, flows, errors, comparisons, and impact questions.
Use definition, usage, graph, or path tools for targeted follow-up.
Call fetch_chunks only with IDs returned from 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.
Check that [mcp].exposed_tools is not unintentionally narrowing the surface.
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

An MCP client can call index_workspace instead, but should ask before mutating local index state.