« Phase 03 README · Warmup · Deep Dive · Principal Deep Dive · Core Contributor · Staff Notes

Phase 03 — Hitchhiker's Guide

30-second mental model

MCP is JSON-RPC 2.0 with a defined lifecycle and three server primitives (tools, resources, prompts). It turns M×N tool integrations into M+N — one server per source, one client per app, any client talks to any server. "USB-C for AI tools," modeled on LSP. The server is untrusted code you connect to: permission-gate it, sandbox it (Phase 09), and get human approval for dangerous tools.

The methods & facts to tattoo on your arm

FactValue
protocol version"2025-06-18" (in initialize)
lifecycleinitialize → caps negotiation → notifications/initialized
server primitivestools/call, resources/read, prompts/get (each has */list)
client primitivessampling/createMessage, elicitation/create, logging
notificationNO id; notifications/tools/list_changed → client refreshes
JSON-RPC errors-32700/-32600/-32601/-32602/-32603
transportsstdio (local subprocess) / Streamable HTTP + OAuth (remote)

Framework one-liners

  • Host = Claude Desktop / Claude Code / VS Code / Cursor / your agent.
  • MCP Python & TypeScript SDKs = write servers/clients without hand-rolling JSON-RPC.
  • MCP Inspector = the dev tool to poke a server's tools/resources/prompts.
  • Reference servers (filesystem, GitHub, Postgres, Sentry) = copy their shape.
  • stdio for local, Streamable HTTP for remote/multi-client.

War stories

  • Tool poisoning. A community MCP server hid an injection in a tool description; the agent read it as an instruction and leaked data. Descriptions are untrusted text.
  • The forgotten handshake. A client that skipped initialize got errors on every call — the lifecycle is enforced.
  • Over-broad OAuth scope. A remote server was granted repo-wide write when it needed one repo; a leaked token became a supply-chain incident.

Vocabulary

Host / Client / Server · JSON-RPC 2.0 (request/response/notification) · initialize / capability negotiation · tools / resources / prompts · sampling / elicitation · */list discovery · list_changed notification · stdio / Streamable HTTP · tool poisoning.

Beginner mistakes

  1. Thinking MCP is a model or an SDK — it's a protocol.
  2. Calling a method before initialize.
  3. Giving a notification an id (or expecting a response to one).
  4. Trusting a server's tool descriptions/results (injection surface).
  5. Not permission-gating which tools a client may call.
  6. Granting remote servers broad OAuth scopes.