MCP servers and clients · Chapter 4 of 16

Your first server

By the end of this chapter you can write an MCP server with the official mcp package: a name and instructions, tools made from plain Python functions, served over stdio. You will know where each part of a tool's listing comes from, how to try a server from the terminal, and the three mistakes that stop a server from ever connecting. 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

In chapter 3 you wrote a server by hand, and it worked: the official client connected to it. It also took you a page of code for one tool, and every schema was typed out by hand, ready to drift away from the function it describes. Rajat's list of apps keeps growing, and every one of them wants stock.

Simran puts it simply: the protocol is the part everybody agrees on, so nobody should write it twice. The mcp package speaks both eras of the protocol, answers every message from chapters 2 and 3 correctly, and builds each tool's listing from the function itself. You write the functions.

What you build: 4 tasks

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

  1. Task 1

    server.py: bazaar-bhai and stock_level

    Write Bazaar Bhai's stock server with the mcp SDK. In server.py, create an MCPServer named bazaar-bhai, with instructions (a sentence or two for the model about what the server is for), and one tool:

    stock_level(store_id, product_id), both strings, returning an int: the quantity from the stock table of /workspace/data/bazaar.db, and 0 when the store does not carry the product.

    Give it a docstring and type hints, and end the file with mcp.run() under if __name__ == "__main__":. The check starts it over stdio, like any client, and nothing but protocol may appear on its stdout.

  2. Task 2

    server.py: a tool that returns a list

    Add a second tool to server.py: low_stock(store_id), returning a list of strings: the ids of the products the store has below their reorder level (its quantity in the stock table is less than the product's reorder_level), sorted by id.

    A store that does not exist has none: an empty list. Give it a docstring too.

  3. Task 3

    client.py: use both tools

    In client.py, start server.py over stdio with the SDK's Client (and sys.executable), then print:

    the instructions the client received from the server, on the first line;

    one line per product that low_stock lists for store BB02, in that order, with its units from stock_level, like P003: 3 units.

    Do not open the database in this file.

  4. Task 4 · interview question

    Interview: fix_me.py, a server that never connects

    fix_me.py is a server for the managers' bot: one tool, store_manager(store_id), returning the manager's name. Every client that starts it fails, and no test can import it. Fix its three bugs, changing as little as you can:

    something it writes on stdout is not a protocol message;

    its tool is registered the wrong way;

    it starts serving when it is imported.

    Keep its tool and what the tool returns.

What you will learn

  • MCPServer: a name, instructions, and mcp.run() over stdio.
  • @mcp.tool(): the docstring becomes the description, the type hints the input schema, the return type the output.
  • Trying a server with lab tools and lab call, and with a client.
  • The stdio rules, from chapter 2, in SDK form: logs on stderr, never on stdout, and mcp.run() under the main guard.

More in The protocol

Build "Your first server" 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.