The MCP server

memtrace mcp exposes the code-intelligence graph to AI coding agents over the Model Context Protocol — 78 tools, stdio or HTTP, adapting its response shape to whichever client connects.

What it is#

memtrace mcp runs the Memtrace MCP server: the process your AI coding agent talks to in order to query the code-intelligence graph. It registers 78 tools — search, relationships, blast-radius, temporal history, quality metrics, graph algorithms, cross-repo API topology, and fleet coordination — over the Model Context Protocol. This is the exact command your MCP client config launches: command="memtrace", args=["mcp"], with no environment variables required at registration time.

The server does not usually boot its own database. In the default local mode it looks for a MemDB already listening on loopback gRPC and either attaches to a running memtrace start daemon or exits with a clear error telling you to start one. See memtrace mcp for the full flag and environment-variable reference.

stdio vs streamable-http#

The default transport is stdio — plain JSON-RPC over standard input/output, which is what every MCP client config expects. The stdio reader is resilient: one unparseable JSON-RPC line gets a -32700 reply and the session keeps serving instead of dying, and the process exits 0 cleanly when the client closes the stream.

Set MEMTRACE_TRANSPORT=streamable-http (aliases http, and legacy sse, which prints a deprecation hint but still works) to instead serve MCP over HTTP at http://0.0.0.0:<MEMTRACE_PORT>/mcp — the shape you want for an orchestrator multiplexing many agent sessions through one long-lived process, rather than one stdio child per client. An unrecognized transport value, or a binary built without the streamable-http feature, exits 2 with a listing of valid values instead of silently falling back to stdio.

Client-adaptive content#

Tool-result content is shaped per client, keyed on clientInfo.name at MCP initialize:

• Claude clients get a two-item split — a human-readable markdown summary (visible in the transcript viewer) plus a compact JSON payload for the model to reason over.
• Codex and every other/unknown client get a single plain JSON content item, with no annotations — Codex's strict client rejects content annotations such as audience/priority.

This is why a bare command="memtrace", args=["mcp"] configuration works identically across clients with no shim, wrapper script, or per-agent config branch — the server decides the response shape at connect time, not the installer.

The attach model#

An MCP client typically launches memtrace mcp as a short-lived child process. Rather than opening a second database, that child adopts a running memtrace start daemon in two layers: it reads ~/.memtrace/runtime.json (repo-scoped — ignored if your cwd's git root doesn't match the daemon's), then <memdb_data_dir>/daemon-state.json to confirm the owner's PID is alive and its loopback endpoint answers within 300ms. On success it prints "attaching to existing workspace owner pid <pid>" and shares the same MemDB — no second daemon, no duplicate index.

memtrace mcp is headless by default: no dashboard/API port is bound unless you pass --ui or set MEMTRACE_MCP_UI=1. It also never spawns the Cortex sidecars (memcortex-daemon/memcortex-mcp) itself — that bootstrap only runs from memtrace start. See memtrace mcp for the complete attach and transport reference.

Tool categories#

The 75 registered tools group into eight categories. Each links to the full reference with per-tool parameters and quota status.

Quota model#

Every tool call passes through a billable-tool gate before dispatch. Only tools on the billable list — 37 of the 75 — consume the plan's monthly query budget. Everything else is free, regardless of plan: fleet coordination, indexing/watch lifecycle, diagnostics, job/worktree plumbing, and plain metadata listing (list_indexed_repositories, get_repository_stats, get_directory_tree) are never metered.

The Community plan meters those 37 billable "insight" tools — search, impact, history, quality, review, architecture — against a default monthly query budget, with an upgrade prompt on exhaustion (the quota error still returns as a successful tool result, not a protocol failure). Plans with teams or no monthly limit set are unmetered. See Plans for what each tier includes.

A tool call, end to end#

A typical session: the client launches the server, lists its tools, then calls one that reads the graph and returns a client-shaped result.

Ready to dig into a specific tool? See the full tool reference, or check the packaged agent skills that route common tasks to the right tool automatically.