MCP servers and clients in TypeScript · Chapter 10 of 16

Errors and validation

By the end of this chapter you can tell the two kinds of failure in MCP apart, validate a tool's input twice (in the zod schema and in the tool, by the policy), write messages a model can act on without giving away how your server works, and make a tool that changes data fail safely, in a transaction. 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

Rajat wants the assistant to draft purchase orders and cancel them, not just read stock. Nisha has read chapter 5's tools and agrees, on three conditions. Bad input is refused with a message the model can fix. The store policy is enforced in the tool, because a model will cheerfully ask to cancel a delivered order. And a change that fails half-way changes nothing.

Until now a tool failing meant a wrong answer. A tool that changes data and fails badly means a purchase order that exists twice, a cancel that went through when the policy said no, or an error message that tells a stranger where your database lives.

What you build: 4 tasks

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

  1. Task 1

    orders.ts: a draft order, checked twice

    In orders.ts, export createServer() that builds an McpServer (any name), served with serveStdio inside if (import.meta.main). When the file starts, copy /workspace/data/bazaar.db to /tmp/bazaar-orders.db and make every change in the copy. Add the tool create_draft_order(store_id, product_id, cases):

    in the schema, store_id has the pattern ^BB\d{2}$, product_id ^P\d{3}$, and cases is a whole number from 1 to 50;

    an error result (isError: true) that names the id for an unknown store or product; one that names the existing draft when the store already has a draft for that product; one that gives the supplier's minimum order value and the number of cases that would reach it (like order at least 3 cases) when the total is below it.

    The order goes to the product's supplier: quantity is cases times case_size, unit_cost the selling price times 0.8 rounded to 2 decimals, total unit_cost times quantity rounded to 2 decimals, the next id (PO-10361 on a fresh copy), status draft, ordered_on 2026-10-22 and expected_on that day plus the supplier's lead days. Insert it and return it as structured content with order_id, store_id, product_id, supplier_id, quantity, unit_cost, total, status and expected_on.

  2. Task 2

    orders.ts: cancel by the policy

    Add cancel_order(order_id), with the pattern ^PO-\d{5}$ in its schema. Policy 6.3: a draft or sent order is cancelled; a delivered one is refused with an error result naming the order and rule 6.3; one already cancelled, or an unknown one, is refused with an error result naming it.

    Change the copy in a transaction (BEGIN, then COMMIT or ROLLBACK), so that a refused or failed cancel changes nothing and leaves the connection ready for the next call, and return as structured content order_id, status (cancelled) and was (the status before).

  3. Task 3

    classify.ts: protocol error or tool error?

    In classify.ts, export async function outcome(client, call): call is ['tool', name, arguments], ['resource', uri] or ['prompt', name, arguments]. Make that request and return 'success', 'tool error' (a result with isError: true) or 'protocol error' (the request rejected with a ProtocolError).

    When run, connect to desk-server.ts and print one line per call in the starter, like 1. tool stock_level: success (the number, the kind, the name or URI, the outcome).

  4. Task 4 · interview question

    Interview: leaky.ts, failures that give too much away

    leaky.ts's failures show the database path, its SQL and a stack trace, one failure comes back as a success, and one tool pastes its argument into the SQL. Fix it, changing as little as you can:

    a failed tool returns an error result whose message names the bad value and shows what a good id looks like, with no path, SQL, stack trace or the word sqlite;

    a supplier that does not exist is not found (-32602), with a message naming it and nothing internal;

    no value is pasted into SQL.

    Keep the tools and the resource, and what they return when they work.

What you will learn

  • Protocol errors and tool errors: which is which, and who handles each.
  • Validation in the schema: patterns and bounds, checked before your code.
  • Validation in the tool: business rules from the policy.
  • Messages that help a retry and never leak internals, in an SDK that sends a thrown error's message to the caller word for word.
  • Failing safe: a transaction around every change, with node:sqlite.

More in Clients and production

Build "Errors and validation" 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.