Model Context Protocol, explained by the thing we built on it

Model Context Protocol is the plumbing that turns a chat model into something that can actually do work on your machine. It is small, boring, and well designed. It is also the reason Claude Recall can expose thirteen tools to Claude Desktop and Claude Code without either side knowing anything special about the other.

This post explains what MCP does at the wire level, then walks a real example using the tools our server ships.

The shape of the protocol

MCP is JSON-RPC 2.0 over stdio. A client (Claude Desktop, Claude Code, Cursor, Windsurf) spawns a server as a subprocess and talks to it over stdin and stdout. No HTTP, no ports, no auth handshake. The server declares the tools it provides, the client lists them, and the model is told about them inside its system prompt.

The three calls that matter:

• initialize — client and server exchange version and capabilities.
• tools/list — client asks for the set of available tools.
• tools/call — model decides to invoke a tool; client forwards the call; server runs it and returns the result.

A minimal tools/list response looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search",
        "description": "Full-text search across indexed Claude Code sessions.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "limit": { "type": "number", "default": 20 }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

The inputSchema is JSON Schema. The model sees the name, the description, and the schema, and decides when to call the tool based on the user's prompt. When it does, the client issues a tools/call with the arguments, the server executes, and the result goes back as a JSON-RPC response.

That is the whole wire protocol. Everything else is conventions.

Why it matters

Before MCP, every tool integration was bespoke. Each vendor shipped its own plugin API, each model had a different function-calling format, and you wrote adapter code for every pairing. MCP collapses that matrix. A server written once works across Claude Desktop, Claude Code, Cursor, Windsurf, and anything else that speaks the protocol. For a tools vendor that is the difference between shipping one thing and shipping four.

For the user it means your agent can touch your real systems (databases, local files, browsers, project history) with one config block and no plugin marketplace.

Claude Recall's six read-only tools

We expose six tools that let the model reach into your session history:

• list_projects — enumerate the cwd-derived projects Recall has seen.
• list_sessions — sessions in a project, filtered by date or tag.
• list_tags — the flat tag namespace.
• search — full-text across every session.
• get_session — fetch the metadata and turns for one session UUID.
• context_for_session — return the condensed or full starting context you would hand to a fresh agent.

A concrete example. You are in a new Claude Code session and you ask: "what did we decide about the rate limiter last month". The model calls:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "query": "rate limiter", "limit": 10 }
  }
}

Recall's server runs the SQLite FTS5 query, returns a list of session UUIDs with snippets. The model picks the one that looks right, calls get_session on it, reads the relevant turns, and now has the decision in context without you having to find it yourself.

Seven write tools in v0.13

The read surface got us most of the way. v0.13 added writes so the model can organize its own history:

• set_alias — rename a session for humans.
• add_tag — attach a tag (auto-filters in the UI).
• remove_tag — detach a tag.
• add_note — free-text note attached to a session UUID.
• pin_session — mark a session as canonical for a decision.
• add_to_collection — put a session into a hand-picked collection.
• apply_tags — batch-tag an array of sessions from a scan result.

The write tools keep the same three-layer durability guarantee as everything else in Recall: the SQLite row is updated, a history row is appended, and the plain-text mirror on disk is regenerated. The source JSONL at ~/.claude/projects/ is not touched.

Config

To plug the Recall MCP server into Claude Code, add a block to ~/.claude.json under mcpServers:

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

Restart Claude Code and tools/list will include the thirteen tools. The MCP doc walks the full setup including Claude Desktop and Cursor, and troubleshooting has the common gotchas (stdio buffering, log location, config precedence).

Takeaway

MCP is quietly the most consequential thing Anthropic shipped in the last year. It made local-first tool integration actually viable. If you are building a developer tool that wants an agent on the other side of it, write an MCP server first and a GUI second. Head to /install to see how Recall's MCP server lands alongside the CLI and the web UI with a single install.