MCP servers and clients · Chapter 14 of 16
Testing servers
By the end of this chapter you can test an MCP server like any other code: in memory with pytest, from a fresh database for every test, over many stores at once, through every error path, in both protocol eras, and with a contract test that fails the day a schema changes. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Clients and production
- 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
Last Tuesday someone "tidied" the stock server and renamed product_id to item_id. Every tool still worked when they tried it. Rajat's assistant, Gopal's bot and the supplier portal all broke at once, because each of them sends product_id, and nobody found out until a store manager complained.
Simran's rule from now on: no change to a server without tests, and a test that fails when the server's contract (its names, descriptions and schemas) changes. Since chapter 4 the lab's checks have been testing your servers. This chapter hands you the tools they use.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
test_stock.py: tests for a server
In test_stock.py, write pytest tests for stock_server.py with the SDK's Client connected in memory to its server object (async tests marked anyio, with an anyio_backend fixture returning asyncio). Test stock_level over several stores and products in one parametrized test, a product the store does not carry (0), a store that does not exist (an error result that names it), and low_stock over several stores (the products below their reorder level, in order), with every expected value computed from the database in the test.
The check runs your tests on stock_server.py, where they must pass, then on three broken copies, each of which must make a test fail.
- Task 2
test_contract.py: a contract test
In test_contract.py, write async def snapshot(), returning a dict from each tool's name to its description, input_schema and output_schema, as stock_server.py's server lists them in memory, and a test that fails unless snapshot() equals the JSON in contract.json, the file next to the test (Path(__file__).parent).
When run with python3, the file writes snapshot() to contract.json, which starts as a placeholder. Run it once to record today's contract. The check runs the test on stock_server.py (it must pass) and on copies with a renamed parameter, another description, a missing tool and a changed output type (each must fail).
- Task 3
test_errors.py: test every way it can fail
In test_errors.py, test every error path of orders.py's tools in memory: create_draft_order refused by the schema (a store id, a product id and cases out of bounds: pydantic's validation error), an unknown store and an unknown product (named in the error), a second draft for the same store and product, and an order below the supplier's minimum; cancel_order refused for a delivered order, an order already cancelled, an unknown order and an id the schema refuses.
Each test starts from a fresh copy of the database: a fixture copies /workspace/data/bazaar.db into tmp_path and points orders.WORK at it. The check runs your tests on orders.py (they must pass) and on five copies with one rule broken each (each must make a test fail).
- Task 4 · interview question
Interview: test_bug.py, find the bug with a test
Time yourself: 15 minutes. One of price_server.py's three tools does not do what its description says. In test_bug.py, write a test, with the in-memory Client, that exposes it: it fails on price_server.py as it is and passes once the bug is fixed (the check runs it on a fixed copy).
What you will learn
- An MCP server in pytest: the in-memory Client(mcp) and anyio.
- Test data: parametrize, and expected values from the database.
- Fixtures: a fresh copy of the database for every test.
- Errors: tool errors, protocol errors, and testing that it is the right error.
- Contract tests: a snapshot of what clients rely on.
- Tests that catch bugs: why passing is not enough.
More in Clients and production
Build "Testing servers" 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.