MCP servers and clients in TypeScript · Chapter 14 of 16
Testing servers
By the end of this chapter you can test an MCP server like any other TypeScript code: in memory with vitest, 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
- TypeScript
- In the all labs plan
The first 2 chapters of MCP servers and clients in TypeScript 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
stock.test.ts: tests for a server
In stock.test.ts, write vitest tests for stock-server.ts with the SDK's Client connected in memory: createMcpHandler serving its createServer, and a StreamableHTTPClientTransport whose fetch is handler.fetch, a fresh pair for every test (beforeEach), closed client first, then handler (afterEach).
Test stock_level over several stores and products in one it.each test, a product the store does not carry (0 units), a store that does not exist (an error result that names it), and low_stock over several stores (the products below their reorder level, sorted by id), with every expected value computed from bazaar.db in the test.
The check runs your tests on stock-server.ts, where they must all pass, then on three broken copies, each of which must make a test fail.
- Task 2
contract.test.ts: a contract test
In contract.test.ts, export async function snapshot(): an object from each tool's name to its description, inputSchema and outputSchema, as stock-server.ts lists them over an in-memory client. Then a test that turns snapshot() into JSON text (two-space indent) and compares it with the file contract.json next to the test, with vitest's toMatchFileSnapshot.
contract.json starts as a placeholder, so record today's contract over it once in the terminal: vitest run contract.test.ts -u (with -u the run writes the file instead of comparing). The check runs your test on stock-server.ts (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
errors.test.ts: test every way it can fail
In errors.test.ts, test every error path of orders.ts's tools in memory: create_draft_order refused by the schema (a store id, a product id and cases out of bounds: the SDK's Input 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: before each test, copy /workspace/data/bazaar.db into a new temporary folder and serve createOrdersServer with that copy's path. The check runs your tests on orders.ts (they must pass) and on five copies with one rule broken each (each must make a test fail).
- Task 4 · interview question
Interview: bug.test.ts, find the bug with a test
Time yourself: 15 minutes. One of price-server.ts's three tools does not do what its description says. In bug.test.ts, write a test, with an in-memory client, that exposes it: it fails on price-server.ts 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 vitest: the SDK's in-process client, with createMcpHandler and handler.fetch.
- Test data: it.each, and expected values from the database.
- A fresh database for every test: pass the server its database.
- Errors: tool errors, protocol errors, and testing that it is the right error.
- Both eras, and one stdio smoke test.
- Contract tests: a file 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. You build it in TypeScript. 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 in TypeScript are free. This one comes with the all labs plan.