Model Context Protocol from the ground up
One wire between a model and the tools it may use
- Advanced
- 10 chapters
- 159 min read
What MCP actually puts on the wire: JSON-RPC requests, responses and notifications, the three server primitives, stdio and Streamable HTTP, and a handshake that negotiates versions and capabilities. Build a server, build a client, then put the two ends in one file and read the transcript.
What You'll Learn
- Explain what MCP standardises and what it leaves to the host
- Read and write JSON-RPC requests, responses and notifications
- Choose between tools, resources and prompts for a capability
- Run a server over stdio and over Streamable HTTP
- Write a server with schemas, validation and error results
- Write a client with an allow-list, timeouts and an audit trail
- Negotiate protocol versions and capabilities without guessing
- Draw a trust boundary around a server and refuse a confused-deputy request
- Test a server at the frame level with transcripts and fuzzed input
- Build a small server and client that talk end to end
Prerequisites
- Comfortable with Python classes, dictionaries and JSON
- You have read a JSON API response and know what a schema is
- No MCP server, SDK install or API key is needed for the examples
Vocabulary
The terms the chapters assume, in plain words.
- capability
- A named feature one side declares it supports during the handshake, such as tools or resources.
- client
- The connector a host creates to talk to one server, sending requests and handling replies.
- handshake
- The opening exchange where both sides agree on a version of the rules and declare what each supports.
- host
- The application the user runs, which creates a client and decides what a model may reach.
- JSON-RPC
- A message format of requests, responses and notifications, where each request carries an id so its reply can be matched.
- notification
- A message that expects no reply, used to report an event or a change.
- prompt
- A reusable message template a server offers, which a user can choose and fill in.
- resource
- Read-only data a server exposes, addressed by a name or address and returned as content.
- schema
- A description of the arguments a tool accepts, used to check a request before it runs.
- server
- The program that offers tools, resources or prompts and answers requests over a transport.
- stdio
- A transport that carries messages over the standard input and output of a program, usually on one machine.
- tool
- A function a server exposes that a model may ask to run, with named arguments and a result.
- transport
- The channel that carries messages between client and server, such as stdio or HTTP.
Course Content
- 01Why a protocolNot started
A model that can call tools is only half a system. The other half is an agreement about what exists and how to ask for it, so any host can use any server without a bespoke adapter.
- 02JSON-RPC messagesNot started
Every MCP message is JSON-RPC 2.0. A request has an id, a response carries the same id, and a notification carries none — get those three shapes right and the rest is method names.
- 03Tools, resources and promptsNot started
MCP has three server primitives with three different contracts: tools are actions the model chooses, resources are data the host attaches, and prompts are templates the user picks.
- 04Transports: stdio and HTTPNot started
stdio is a pipe and HTTP is a request; both carry the same JSON-RPC frames. Choose by where the server lives, and treat the transport as the first security boundary rather than a detail.
- 05Writing a serverNot started
A server is a dispatch table plus a schema. Start with one read-only tool, validate at the edge and again inside, and let the SDK do the framing while you keep the effects honest.
- 06Writing a clientNot started
The client owns the connection, the capabilities and the policy. It is the place where a tool call becomes a decision rather than a reflex, and where a hostile server meets its limits.
- 07Capabilities and negotiationNot started
Capabilities are a promise about methods, not a score. Each side declares what it can answer, and the other side must not call what was never declared, however clearly the specification describes it.
- 08Security and trust boundariesNot started
The model proposes, the host consents and the server acts with whatever authority it was given. Tool descriptions and results are untrusted input, and the confused deputy is the failure mode to design against.
- 09Testing an MCP serverNot started
A handler test does not prove the server speaks MCP. Test the frames, keep a readable transcript as the fixture, and spend most of the suite on the error paths a client will actually meet.
- 10Capstone: a small server plus clientNot started
One file, two ends: a server with tools and a resource, a client that negotiates, lists, calls and blocks, and a transcript of every frame between them.