MCP servers and clients in TypeScript · Chapter 4 of 16

Your first server

By the end of this chapter you can write an MCP server with the official TypeScript SDK: a name and instructions, tools with zod schemas, built by a factory and served over stdio. You will know where each part of a tool's listing comes from, what a tool's handler must return, 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
  • 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

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 the schema was typed out by hand, ready to drift away from the code 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 SDK speaks both eras of the protocol, answers every message from chapters 2 and 3 correctly, checks arguments against the schema, and builds each tool's listing from the zod schema you give it. You write the tools.

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.ts: bazaar-bhai and stock_level

    Write Bazaar Bhai's stock server with the MCP SDK. In server.ts, export createServer(), which builds and returns a new McpServer named bazaar-bhai (any version), with instructions (a sentence or two for the model about what the server is for), and one tool:

    stock_level, with a description, an inputSchema of two required strings, store_id and product_id, and an outputSchema for the object it returns. Its result has the structured content { store_id, product_id, units }, the units from the stock table of /workspace/data/bazaar.db (0 when the store does not carry the product), and the same JSON as text in its content.

    Serve it with serveStdio(createServer) only inside if (import.meta.main). The check imports createServer, and also starts the file over stdio, where nothing but protocol may appear on stdout.

  2. Task 2

    server.ts: a tool whose result holds a list

    Add a second tool to server.ts: low_stock, with a description and one string argument, store_id. Its structured content is { products: [...] }, 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, with the same JSON as text in its content.

    A store that does not exist has none: { products: [] }.

  3. Task 3

    client.ts: use both tools

    In client.ts, start server.ts over stdio with the SDK's Client (and process.execPath), 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.

    Close the client at the end. Do not open the database in this file.

  4. Task 4 · interview question

    Interview: fix-me.ts, a server that never connects

    fix-me.ts is a server for the managers' bot: one tool, store_manager, which gives the manager's name for a store_id. Clients that start it misbehave, 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 handler does not return an MCP result;

    it starts serving when it is imported.

    Keep its name, its tool, and the manager's name as the tool's text.

What you will learn

  • McpServer: a name, a version and instructions.
  • registerTool: a name, a description, zod schemas for the input and the output, and a handler that returns the MCP result itself.
  • The createServer factory and serveStdio under if (import.meta.main): the shape of every server in this lab.
  • 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.

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. 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.