What is the Model Context Protocol (MCP)?

TL;DR

MCP (Model Context Protocol) is a JSON-RPC-over-stdio standard from Anthropic that lets a coding agent (Claude Code, Codex CLI, Cursor, Cline, Continue.dev, and many others) call tools exposed by a separate process. The agent spawns the MCP server, talks to it on stdin/stdout, and exposes the tools to the model. Build one server, plug it into every agent.

Where MCP came from

Anthropic published the MCP specification in late 2024. The official spec lives at spec.modelcontextprotocol.io. Before MCP, every coding agent had to invent its own tool-calling mechanism — Claude Code had one, Cursor had a different one, every other agent had a third. Tool authors paid the cost of writing N adapters for N clients.

MCP changes that. The spec defines how a client discovers tools, how it calls them, how results come back, and how errors propagate. Any agent that speaks MCP can talk to any server that speaks MCP — the same way HTTP lets any browser talk to any web server.

How MCP actually works

Three pieces:

Client: the agent harness (Claude Code, Codex, Cursor, Cline). It spawns the server process and reads its capabilities.
Transport: stdio. The client writes JSON-RPC messages to the server's stdin and reads responses from stdout. There's also an SSE/HTTP transport in the spec, but stdio is the dominant one for local tools.
Server: the process that exposes tools. agentmako mcp is one example. It registers a list of typed tools at startup, waits for calls, and returns structured results.

A typical exchange:

// JSON-RPC over stdin/stdout

// client → server
{"jsonrpc":"2.0","method":"tools/list","id":1}

// server → client
{"jsonrpc":"2.0","id":1,"result":{"tools":[
  {"name":"context_packet","inputSchema":{...}},
  {"name":"reef_scout","inputSchema":{...}}
]}}

// client → server
{"jsonrpc":"2.0","method":"tools/call","params":{
  "name":"context_packet",
  "arguments":{"request":"trace the auth callback"}
},"id":2}

The model never speaks MCP directly. The harness sees the tools list, decides which to call based on the user prompt, and forwards the call to the server. The server's response comes back as a tool result, which the model then reads.

Why one server, every agent matters

Without MCP, a tool like agentmako would need custom integrations for Claude Code, Cursor, Codex, Cline, and every other agent. Each integration would drift independently. Each would have its own auth model, its own input/output shape, its own restart semantics.

With MCP, agentmako ships one server. It registers in ~/.claude.json for Claude Code, ~/.codex/config.toml for Codex, .cursor/mcp.json for Cursor, and a Cline settings panel — but the server binary is the same in all four cases. New agents that adopt MCP get agentmako support for free.

For a coding-intelligence server, the value compounds: the same indexed graph of routes, schemas, and findings is available everywhere the developer works.

What MCP is not

Not a model. MCP doesn't ship inference. It's plumbing for tool calls.
Not a hosted service. The default transport is stdio. Most MCP servers (including agentmako) run entirely locally.
Not Anthropic-only. The spec is open. OpenAI's Codex CLI, Cursor (Anysphere), Cline, and many others implement it.
Not a vector database. An MCP server can implement vector search if it wants to, but the protocol itself says nothing about retrieval strategy.

agentmako as an MCP server

agentmako is a local-first MCP server purpose-built for code intelligence. It indexes your repo into local SQLite, snapshots your Postgres or Supabase schema (when configured), tracks diagnostics across runs, and exposes 85 typed tools ranging from context_packet (vague request → ranked context) to route_trace (URL → handler → schema) to db_rls (table → row-level-security policies).

The MCP layer is what makes those tools available everywhere. The agent doesn't care which language they're written in, where they store their data, or how the index works — it just sees the tools list and calls what fits.

Install:

// quickstart

$ npm install -g agentmako
$ cd /path/to/your/project
$ agentmako connect . --no-db
$ agentmako mcp        # speak MCP on stdio

Then add the server to your agent. Setup guides: Claude Code, Codex CLI, Cursor, Cline.

MCP vs. other integration approaches

Before MCP, "give the agent a tool" usually meant one of three things. Each has tradeoffs MCP is built to avoid:

Per-agent plugin SDKs. Claude Code had one, Cursor had another, Continue had a third. You wrote N adapters for N agents. Each adapter drifted. MCP makes the tool author the single source — write once.
Shell-out to a CLI. The agent runs a command, parses stdout. Works, but the contract is a string — no schema, no introspection, no error model. MCP gives tools typed input/output schemas the agent reads at startup.
HTTP API for everything. Spin up a local web server, give the agent a base URL. Now you have ports, auth, CORS, lifecycle, and a hosted service to run even when nothing else is running. MCP runs as a child process of the agent, no networking required.

The MCP server design follows the same logic as a Unix tool: do one thing, communicate over stdio, exit when the parent closes. That's why most MCP servers are 50-line wrappers around an existing library — the protocol gets out of the way.

Protocol notes worth knowing

Initialization is two-step. The client sends initialize with its capabilities, the server responds with its own. Then the client sends initialized as the handshake. Tools aren't available until that handshake completes.
Tool calls are JSON-RPC requests. The client sends tools/call with name + arguments, the server replies with content (text, image, resource). Errors come back as JSON-RPC error objects, not exceptions.
Streaming is optional. A tool can stream progress notifications during a long call. Most agents render these as inline status updates.
The transport is reusable. stdio is default, but the spec also defines an SSE/HTTP transport for remote tools. agentmako uses stdio — the local-first assumption is baked in.
Tool discovery is static, not dynamic. The client gets the tool list once at startup. If the server adds a new tool mid-session, the client won't see it until reconnect. Restart the agent after upgrading the server.

Common pitfalls

Wrong PATH at agent launch. The agent inherits PATH from the shell that launched it. If you installed agentmako in a terminal but launched the agent from a desktop shortcut, PATH may not include the npm global bin. Run the agent from the same shell, or restart after install.
Tools listed but never called. The agent decides when to call MCP tools based on prompts. Without explicit guidance (CLAUDE.md / AGENTS.md), it defaults to its built-in tools. Tell it which Mako tools to reach for and when.
Configuring the server but not restarting the agent. MCP discovery happens at startup. Editing ~/.claude.json or .cursor/mcp.json without restarting means the agent is still talking to the old config.
Multiple servers, same tool name. If two servers expose a tool called search, the agent can't disambiguate. agentmako prefixes its tools with mako-ai__ via the server name in your config — keep server names unique.