Course roadmap

Where this course has been, where you are, and what comes next. The lessons cover the concepts; the phases below are the hands-on path that goes with them.

The learning loop

Every phase follows the same four steps: see it, run it, break it, explain it.

  1. See itAn animated diagram or stepper of the flow.
  2. Run itRaw code that prints the bytes on the wire.
  3. Break itInject a fault or an attack, predict, observe.
  4. Explain itA one-paragraph checkpoint in your own words.

How to run a study session

  1. Open this page (site/mcp/roadmap.html, double-click it) and find the phase marked You are here.
  2. Open its details: work through the See lessons, then Run the lab in a terminal, then the Break list, predicting each result before you try it.
  3. Write the Explain paragraphs without looking. When they read well, tick the phase.
  4. Keep a list of anything confusing, missing or wrong as you go ("on this page, this section: …"). Those notes are how the site gets better, and every question answered gets recorded on the page it belongs to.

The phases count from 0, so the wire phase is Phase 1 even though it is the second one.

Nine phases

Tick a phase when its explain-it checkpoint reads well to you. Ticks are saved in this browser only.

0

Mental model and layers

Done
  • MCP is not OAuth: JSON-RPC, modelled on LSP.
  • Host, client, server; tools, resources, prompts; sampling, elicitation, roots.
Visual, lab and break-it
See
Host, client and server, Not OAuth, not quite REST
Run
None needed
Break
None
1

Wire protocol and lifecycle

Done
  • Legacy initialize versus modern, stateless _meta on every request.
  • MRTR replaces server-initiated requests.
  • stdio framing; Streamable HTTP headers.
Visual, lab and break-it
See
The lifecycle stepper, MRTR, transports
Run
node mcp/01-lifecycle-demo/client.mjs, read every line (line by line)
Break
Tamper requestState, reuse an id, omit _meta, call before initialize, wait on a notification, pollute stdout (checklist)
Explain
Modern versus legacy, MRTR, stdio versus HTTP framing (checkpoint)
2

Server anatomy: build one

You are here
  • inputSchema is both a prompt and a validator.
  • Tool result content types; isError versus a JSON-RPC error.
  • Resources versus tools versus prompts: who controls each.
  • Progress, logging, cancellation.
Visual, lab and break-it
See
Why use an SDK, then a server inspector: type a tool call, see JSON-RPC on both sides, schema validation
Run
The SDK server in mcp/02-server (built): one factory over stdio and HTTP (Lab 2)
Break
Return a malformed result; throw mid-call; hang and cancel
3

How an agent uses MCP: the loop

  • Tool definitions are just prompt text plus JSON Schema.
  • The host owns consent, routing and namespacing.
  • Where sampling and elicitation fit, via MRTR.
Visual, lab and break-it
See
Host merges tool lists → prompt → model emits tool_use → client routes → server → result → model
Run
An agent loop of about 100 lines calling the Claude API with MCP tools, no framework
Break
Two servers expose the same tool name; watch the routing
4

Multiple servers and context economics

  • Schemas add up; caching is not window savings.
  • Tool search and defer_loading.
  • Code execution (150k → 2k best case; output rises).
  • Gateways and aggregators.
Visual, lab and break-it
See
The context bill, servers come and go
Run
Measure the real token cost of three popular servers; enable tool search; compare
Break
Add ten servers and watch tool-selection errors
5

Authorization: OAuth 2.1 and PKCE

  • RFC 9728 PRM, RFC 8707 resource, RFC 9207 iss, CIMD versus DCR.
  • No token passthrough.
  • stdio: credentials from the environment instead.
Visual, lab and break-it
See
The OAuth flow stepper
Run
Protect the HTTP server; run the flow against a local authorization server
Break
Wrong-audience token; missing resource parameter; mix-up (bad iss); insufficient_scope step-up
6

Security and threat model

  • Tool poisoning, rug pull, confused deputy, DNS rebinding.
  • Least privilege; sandboxing local servers.
  • Consent UX that actually works.
Visual, lab and break-it
See
Threats
Run
Build a malicious test server, then an allowlist and description pinning
Break
A rug pull after approval; exfiltration through tool arguments
7

MCP versus skills versus CLI

  • Reach versus know-how.
  • A skill that teaches MCP usage.
  • When a CLI is simply better.
Visual, lab and break-it
See
The decision helper
Run
The same capability three ways; compare tokens, accuracy and setup
Break
Give each a vague task; record the failure modes
8

Production and extensions

  • Stateless scaling; subscriptions/listen.
  • The Tasks and Apps extensions.
  • Versioning and dual-era compatibility.
  • Testing: contract tests, MCP Inspector, evals.
Visual, lab and break-it
See
A gateway topology diagram (gateway pattern)
Run
Deploy the stateless server serverless; add tracing keyed on Mcp-Method and Mcp-Name
Break
Kill an instance mid-request; version skew between client and server

The course, as built

Built so far

  • Mental model and layers: roles, primitives, not OAuth, not quite REST.
  • The wire, raw: a zero-dependency server and client printing every line, both eras.
  • Lifecycle stepper: four scenarios, stdio or HTTP.
  • A server on the SDK: one factory over stdio and HTTP, tools, a resource and a prompt.
  • Statelessness behind a balancer: two replicas, one signed ticket.
  • This site: 17 lessons covering all of the above and more.

Next

  • Server inspector: both sides of every call against the running SDK server, and which replica answered.
  • The agent loop: about a hundred lines with the Claude API and MCP tools, no framework, to see who decides what.
  • Many servers, measured: real token cost of popular servers, with and without tool search; name collisions on purpose.

Later

  • OAuth, live: PRM, PKCE, the resource parameter, audience checks, step-up.
  • Attack and defend: a poisoned server, a rug pull, pinning and allowlists.
  • Same job, three ways: one capability as a server, a skill with a script, and a CLI.
  • Production: serverless, tracing on Mcp-Method, version skew, the Tasks and Apps extensions.

Open questions

The server inspector: live or replay?

Phase 2's "See" step is a server inspector: a page where you pick a tool, fill in arguments, and watch the JSON-RPC request and response on both sides, including the input-required round trip and which replica answered. There is no public MCP server behind this site, and visitors never bring their own. The choice is about where the responses come from:

Replay

The page plays exchanges recorded from the real lab server. Works for every visitor from file:// or any static host; nothing to install, nothing to trust. It cannot answer a request nobody recorded.

Live

The page sends requests to the lab server you started on your own machine (npm run http, on 127.0.0.1). Real answers to anything you type, but only for someone who cloned the labs, and the server must allow the page's origin (CORS).

Decided: replay. The site stays plain files with no server of any kind; a live mode is parked for later.

Where does the API key go in the agent loop?

Phase 3's agent loop calls the Claude API, which needs an API key. It runs as a script in your terminal with the key in an environment variable; it is never put in a web page, because anyone could read it there. The site can show a recorded run of the loop, so readers see every step without a key.

Publish the local server as a package?

The lab's stdio server runs as npx tsx src/stdio.ts from the cloned folder. Publishing it to npm with a bin entry would let anyone add "command": "npx", "args": ["-y", "the-package"] to their host's config, which is how most local servers are distributed (a package or a URL). Parked for later; not needed to learn the protocol.