MCP server project · 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 Bhavna 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
- Python
- In the all labs plan
The first 2 chapters of MCP server project 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.
- DabbaDrop said no: the 12:30 slot is full, a dish is not on that kitchen's menu. That message is useful; the assistant can tell Tara and offer 13:00.
- 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 answers only
Error executing tool pay_order, and writes a 400-line traceback to the log that nobody can match to Tara's call.
And there is no record of calls at all. In launch week Bhavna 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.py: refusals and bugs
Write guard(name, fn) in mcp_server/errors.py: an async wrapper (with @wraps(fn)) that makes a trace id (secrets.token_hex(4)), checks the member's scope with check(current_member(), name), returns await fn(...), lets a ToolError through unchanged, turns any other exception into ToolError("Something went wrong at DabbaDrop (trace <trace>). Nothing more is known; try again later.") after logging it with log.exception, and always calls log_call(name, the member's id, outcome, ms, trace) with outcome ok, refused or error.
The Check wraps tools of its own: one that returns, one that raises ApiError, one that crashes with a message holding SQL, and one called with a read-only member's token for place_order. It reads what the assistant gets, the log, and the line log_call is given; then it breaks the API under find_slots and calls it through MCP.
- Task 2
errors.py: timeouts
In guard, run fn inside anyio.fail_after(mcp_settings.tool_timeout). On TimeoutError raise ToolError("DabbaDrop did not answer within <s> seconds. Try again in a minute.") for a read-only tool, or ToolError("DabbaDrop did not answer within <s> seconds, so this may or may not have gone through. Call list_my_orders to see before trying again.") for one that changes something, with s written with :g; the log line's outcome is timeout.
The Check sets the tool timeout to 0.3 seconds and wraps a slow find_slots and a slow place_order of its own.
- Task 3 · interview question
Interview: tracing.py, one line per call
Write setup_logging, call_line and log_call in mcp_server/tracing.py. setup_logging gives the logger dabbadrop one StreamHandler on sys.stderr with the format %(message)s, level INFO and propagate False, only when it has no handler. call_line(tool, member, outcome, ms, trace) is the JSON of {"mcp": "tools/call", "tool", "member", "outcome", "ms" rounded to 1 decimal, "trace"} in that order. log_call logs that line at INFO on the logger dabbadrop.mcp.calls.
The Check calls setup_logging twice, reads your lines, and starts python -m mcp_server --stdio with Tara's token: the call's line must be on stderr, never on stdout.
Kunal 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 leak a bug's message: what a real one holds, and a trace id instead.
- Timeouts: anyio.fail_after, and why a read and a write need different words afterwards.
- One JSON line per call: Python's logger tree, a handler 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
DabbaDrop wants AI assistants like Claude Desktop to order 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 are free. This one comes with the all labs plan.