The MCP server

memtrace mcp exposes code intelligence, docs, and Cortex decision memory to AI coding agents over the Model Context Protocol — 83 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 code intelligence and decision memory. It registers 83 tools — search, relationships, blast-radius, temporal history, quality metrics, graph algorithms, cross-repo API topology, fleet coordination, hosted docs, and five Cortex tools — 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. If no compatible owner is reachable, the MCP child becomes the workspace owner and starts the local MemDB sidecar before it serves tools.

memtrace mcp is headless by default: no dashboard/API port is bound unless you pass --ui or set MEMTRACE_MCP_UI=1. An attached client reuses the owner's Cortex endpoint; an MCP process that becomes owner bootstraps Cortex itself. See memtrace mcp for the complete ownership, attach, and transport reference.

Tool categories#

The 83 registered tools comprise 75 core graph/runtime tools, three hosted-docs tools, and five Cortex decision-memory tools across eleven categories. Each card links to the full reference.

Quota model#

Every tool call passes through a billable-tool gate before dispatch. Of the 75 core graph/runtime tools, 37 consume the plan's monthly query budget. Everything else in that core set 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.