MCP server project (TypeScript) · Chapter 9 of 12
Errors, timeouts and logging
By the end of this chapter every tool call goes through one wrapper that checks the token's scope, gives the call a time limit, tells the assistant something it can act on when the call fails (and nothing about the server's insides when it is a bug), and writes one JSON line per call to the server's log, which Asha reads when a member asks "what did my assistant do?". Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Ready for every assistant
- 3 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of MCP server project (TypeScript) are free. This one comes with the all labs plan.
Why you need this
A tool can fail in three very different ways, and today the assistant hears about each one badly.
- Parda said no: seat E1 is taken, the hall has no row Z. That message is useful; the assistant can tell Neha and offer E3.
- It took too long: Postgres was busy, a migration held a lock. The assistant needs to know whether to try again.
- A bug: a migration that did not run, a typo. Here the SDK sends the error's own message to the assistant, whatever it holds.
To see the third, we renamed a column in chapter 8's database, amount in mcp_approvals, as a migration that did not run would leave it, and asked pay_booking to pay booking 3. The text the assistant got:
Failed query: select "id", "user_id", "booking_id", "amount", "status", "created_at", "decided_at", "used_at" from "mcp_approvals" where ("mcp_approvals"."user_id" = $1 and "mcp_approvals"."booking_id" = $2 and "mcp_approvals"."amount" = $3 and "mcp_approvals"."status" = $4) order by "mcp_approvals"."id" asc limit $5 for update
params: 2,3,400,approved,1
The table, every column, the query, Neha's user id and the amount, all sent to a model, which may repeat it to Neha or to anyone who asks it the right question. And there is no record of calls at all. In Diwali week Asha will get messages like "my assistant booked twice" or "it said something went wrong". The server log shows the API's requests, but not which tool call made them, for which member, or how it ended.
What you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
errors.ts: refusals and bugs
Write guard(name, fn) in src/mcp/errors.ts: it returns async (args, extra) => ... that makes a trace id (randomBytes(4) in hex), finds the member (currentMember(extra)), checks their scope (check(member, name)), returns await fn(args, member), lets a ToolError through unchanged, turns any other error into ToolError("Something went wrong at Parda (trace <trace>). Nothing more is known; try again later.") after writing "tool <name> failed (trace <trace>): <stack>" with log.write, and always calls logCall(name, the member's id or null, outcome, ms, trace) with outcome ok, refused or error.
The Check wraps tools of its own: one that returns, one that throws an ApiError, one that crashes with a message holding SQL, and hold_seats called with a read-only member. It reads what the assistant gets, the log, and the line logCall writes; then it points the tools at an API that is down and calls find_showtimes through MCP.
- Task 2
errors.ts: timeouts
Write within(ms, work) in src/mcp/errors.ts: work's result, or a rejection with a new TimedOut() after ms milliseconds (Promise.race with a timer that is cleared when either ends). In guard, run the tool as within(mcpConfig.toolTimeout * 1000, fn(args, member)); on a TimedOut throw ToolError("Parda did not answer within <s> seconds. Try again in a minute.") for a read-only tool, or ToolError("Parda did not answer within <s> seconds, so this may or may not have gone through. Call list_my_bookings to see before trying again.") for one that changes something; the log line's outcome is timeout.
The Check races within against a quick and a slow promise, then sets the tool timeout to 0.3 seconds and wraps a slow find_showtimes and a slow hold_seats of its own.
- Task 3 · interview question
Interview: tracing.ts, one line per call
Write callLine, log.write and logCall in src/mcp/tracing.ts. callLine(tool, member, outcome, ms, trace) is JSON.stringify of { mcp: 'tools/call', tool, member, outcome, ms rounded to 1 decimal, trace } in that order. log.write(line) writes the line and a newline to process.stderr. logCall writes callLine(...) with log.write.
The Check reads your lines, catches what log.write writes to stderr and stdout, and starts main.ts --stdio with Neha's token: the call's line must be on stderr, never on stdout.
Nikhil will ask: a member says the assistant booked twice. What do you look for in this log, and why are the call's arguments not in it?
What you will learn
- Three kinds of failure: a refusal the assistant can act on, a timeout, a bug.
- Never send a bug's message: a trace id instead, and the stack in the log.
- Timeouts: Promise.race against a timer, and why a read and a write need different words afterwards.
- One JSON line per call, on stderr, and why stderr.
- What a log line holds, and what it must not.
More in Ready for every assistant
Build "Errors, timeouts and logging" yourself
Parda wants AI assistants like Claude Desktop to book seats for its members, safely. You build the MCP server that lets them, and only as the member who allowed it. 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 server project (TypeScript) are free. This one comes with the all labs plan.