MCP server

The MCP server is a subcommand of the single oxcode binary: oxcode mcp. It is a stdio server that exposes oxcode's read-only queries to coding agents (Claude, Cursor, and others). It is the recommended way to give an agent code context: the same bounded, PageRank-curated context arrives in one tool call instead of a CLI the agent has to compose.

Setup

Point an MCP-capable agent at the server, then have it call oxcode_watch once: that builds the .oxcode/ index and keeps it current as files change, so there is nothing to run by hand. The server reads the index from its working directory (or a path you pass). The config shape is the same across clients:

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

Claude Code

The fastest path is the bundled plugin — it ships this config, so there is no file to edit:

/plugin marketplace add oxgraph/oxgraph
/plugin install oxcode@oxgraph

The plugin only adds the MCP wiring: you still need the oxcode binary on your PATH (see Getting started). The agent builds the index itself the first time it calls oxcode_watch. Refresh the plugin later with /plugin marketplace update oxgraph.

To wire it by hand instead, add the server to ~/.claude.json:

{
  "mcpServers": {
    "oxcode": { "type": "stdio", "command": "oxcode", "args": ["mcp"] }
  }
}

The query tools are read-only and oxcode_watch only writes the local index, so you can auto-allow them in ~/.claude/settings.json to skip per-call approval:

{
  "permissions": {
    "allow": [
      "mcp__oxcode__oxcode_watch",
      "mcp__oxcode__oxcode_explore",
      "mcp__oxcode__oxcode_search",
      "mcp__oxcode__oxcode_callers",
      "mcp__oxcode__oxcode_callees",
      "mcp__oxcode__oxcode_symbol",
      "mcp__oxcode__oxcode_files",
      "mcp__oxcode__oxcode_status"
    ]
  }
}

Tools

Call oxcode_watch once up front to build and maintain the index. Then, for almost any code-understanding question, the agent should call oxcode_explore first with the question verbatim, then follow specific edges with oxcode_callers / oxcode_callees / oxcode_symbol, and fall back to oxcode_search / oxcode_files only when explore did not surface the target.

Running several agents

oxcode mcp is safe to run from many agents against the same repo at once. The first to call oxcode_watch takes a .oxcode/watch.lock advisory file lock and becomes the writer — the one process that watches for changes and re-indexes. The rest become readers that serve queries off the shared index, and a reader automatically takes over as writer if the current writer exits (the kernel frees the lock on process death). So there is never more than one writer, and the index stays current as agents come and go. This is same-machine coordination — it does not span hosts or network filesystems.

Tune the watcher with two environment variables: OXCODE_WATCH_DEBOUNCE_MS (how long the writer coalesces a burst of edits before re-indexing, default 400) and OXCODE_WATCH_POLL_MS (how often a standby retries the writer lock so it can take over, default 3000).

Why MCP is the headline

On the Tokio agent-task benchmark, the one-call oxcode_explore MCP tool cuts tool calls 84%, tokens 74%, cost 57%, and wall time 60% versus the no-tool baseline — exceeding codegraph's published reductions. The CLI arm, by contrast, is statistically tied with the baseline: an agent treats a shell binary as a supplement to its own grep/read, not a replacement. The gap was always tool delivery, not index quality.

See Benchmarks for the full table.