MCP server

ctx speaks the Model Context Protocol over stdio — JSON-RPC 2.0, one message per line. There is no daemon and no network port. The client spawns ctx mcp as a child process, and all logs go to stderr so stdout stays protocol-clean.

Global install (Claude Desktop, opencode)

opencode / Claude Desktop

{
  "mcpServers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "-R", "/path/to/project"]
    }
  }
}

No install needed (npx)

If you don't want a global install, npx will fetch the package on first use:

opencode / Claude Desktop

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/path/to/project"]
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/path/to/project"]
    }
  }
}

VS Code / Cline / Roo

mcp.json

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/path/to/project"]
    }
  }
}

Prerequisites: index first

The tools read a local SQLite index. The server does not index on its own — point it at a project that has been indexed with ctx init first:

build the index, then serve it

cd /path/to/project
ctx init
ctx mcp -R /path/to/project

Smoke test over stdio

Confirm the handshake and tool list without an agent client:

verify the handshake

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | ctx mcp

You should see an initialize response naming ctx, followed by the eleven tools below.

The eleven tools

All tools are read-only — they read the index and never modify your repository:

Tool	Purpose
ctx_project	Project overview: root, git status, index counts.
ctx_search	Find symbols or files by name, with kind and file filters.
ctx_skeleton	Body-less structural skeleton of a file.
ctx_symbol	Definition, kind, methods, references and dependencies of a symbol.
ctx_dependencies	What a file imports.
ctx_dependents	What imports a file.
ctx_impact	What would break if a symbol or file changed.
ctx_context	Relevance-ranked context package for a task.
ctx_changed	Symbols changed in the working tree or since a ref.
ctx_diff	Symbol-level diff between two refs.
ctx_stats	Index statistics: files, symbols, dependencies, db size.

What the server can and cannot see

The index is a snapshot. Re-run ctx init (or keep ctx watch running) after adding or renaming files so the tools see them.
ctx_context ranking is name-based, not semantic. The agent should describe the task with the same words that appear in symbol and file names.
Context following is limited to direct dependency and dependent edges from matching files. Symbols reachable only through a longer chain may not appear.
Only TypeScript, JavaScript, Python, Rust, and Go are parsed. Other files are invisible to the tools.

Protocol notes

The server negotiates the 2025-06-18 protocol version. Failures surface as isError: true in tool results rather than unhandled exceptions, so the client keeps running. Stdout is reserved for protocol frames — everything else goes to stderr.

The server reads source code only through its index. It does not execute project code, does not open network connections, and never uploads anything.