MCP servers and clients · Chapter 3 of 16

The handshake

By the end of this chapter you can explain how an MCP client and server agree on a protocol version and on what each can do, in both eras of the protocol: the initialize handshake used up to 2025-11-25, and the 2026-07-28 way with no handshake at all. You will do both by hand, and write a server the official client accepts. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The protocol
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of MCP servers and clients are free. This one comes with the all labs plan.

Why you need this

Gopal's price checkers are on the counters, and the vendor's next request is reasonable: "before we send anything, tell us which version of MCP you speak." Meanwhile Rajat has found an AI app he likes, and it is two years old. The new assistant his office is building is brand new. Both must use the same Bazaar Bhai server.

A protocol that changes over time needs a way for two programs, written years apart by different people, to find out what the other understands. In chapter 2 you sent requests straight away; a real MCP connection first settles who is talking, which version they share, and what each side supports. Simran wants you to see those messages, because when an old client and a new server fail to connect, this is where it happens.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    handshake.py: three messages, then the tools

    stock_server.py is built with the SDK and speaks the handshake era too. In handshake.py, with json and subprocess only, start it with pipes and send initialize (id 1) with protocolVersion 2025-11-25, capabilities {} and clientInfo {"name": "handshake", "version": "1.0"}. From the result, print three lines:

    Server: <the name in serverInfo>

    Protocol: <the version the server agreed to>

    Capabilities: <the capability names, in the order they came, joined by a comma and a space>

    Then send the notification notifications/initialized, send tools/list (id 2), and print one line per tool: Tool: <name>.

  2. Task 2

    versions.py: the server proposes, the client decides

    Three old clients each speak exactly one version: 2024-11-05, 2025-06-18 and 1999-01-01 (a made-up one). In versions.py, for each, start a fresh stock_server.py, send initialize asking for that version, and read the version the server agrees to.

    A client can go on only if the server agreed to the version it speaks. Print one line per version, in that order:

    <asked> -> <agreed>: accept, or <asked> -> <agreed>: reject

  3. Task 3

    discover.py: no handshake, an envelope instead

    In the 2026-07-28 protocol there is no initialize: every request carries the envelope in params._meta, with the keys io.modelcontextprotocol/protocolVersion (2026-07-28), io.modelcontextprotocol/clientInfo ({"name": "discover", "version": "1.0"}) and io.modelcontextprotocol/clientCapabilities ({}).

    In discover.py, with json and subprocess only, start stock_server.py and send server/discover (id 1) with the envelope. Print Server: <name> (from the result's own _meta, under io.modelcontextprotocol/serverInfo) and Supported versions: <the supportedVersions, joined by a comma and a space>.

    Then send tools/call (id 2) for stock_level with store BB14 and product P052, with the envelope too, and print BB14 P052: <units> units from its structuredContent.

  4. Task 4 · interview question

    Interview: my_server.py, an MCP server with no SDK

    Write an MCP server by hand in my_server.py (json, sys and sqlite3 only; no mcp package) that the official client in legacy mode can use. One JSON-RPC message per line on stdin, one reply per line on stdout, flushed:

    initialize agrees to the client's protocolVersion when it is one of 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25, and to 2025-11-25 otherwise; its result has protocolVersion, capabilities with tools, and serverInfo with a name and a version.

    Notifications are never answered; ping answers {}.

    tools/list lists stock_level with a description and an inputSchema: an object with two required string properties, store_id and product_id.

    tools/call for stock_level answers with content (one text item holding the JSON), structuredContent {"store_id", "product_id", "units"} (0 units when the store does not carry the product) and isError false.

    tools/list and tools/call before initialize are refused with the error code -32602.

What you will learn

  • The initialize handshake: three messages, and what each carries.
  • Version negotiation: the server proposes, the client decides.
  • Capabilities: what each side says it can do.
  • The 2026-07-28 protocol: server/discover and the _meta envelope on every request, with no handshake.
  • What the SDK's client does: try the new way, fall back to the old.

More in The protocol

Build The handshake yourself

Bazaar Bhai, a chain of 40 kirana stores in Jaipur, exposes its stock and orders once, to every AI tool. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of MCP servers and clients are free. This one comes with the all labs plan.