Capstone: build a stdio MCP server
Write a working MCP server from scratch that discovers, lists and calls a tool over stdio.
- Read newline-delimited JSON-RPC requests from stdin
- Answer server/discover, tools/list and tools/call correctly
- Return the right kind of error for every failure
Time to build the whole thing. Your server will speak MCP over stdio: one JSON-RPC request per line on stdin, one response per line on stdout. In practice you would use an official SDK, which handles this plumbing for you - but writing it once by hand shows exactly what the SDK does, and makes every bug you meet later easier to understand.
Your server must handle:
| Request | Response |
|---|---|
any request missing a required _meta field | error -32602 “Missing required _meta” |
server/discover | supportedVersions: ["2026-07-28"], capabilities: {"tools": {}} |
tools/list | the add tool definition |
tools/call for add with integer a and b | the sum as text content, structuredContent: {"sum": …}, isError: false |
tools/call for add with bad arguments | a tool execution error, isError: true |
tools/call for an unknown tool | error -32602 “Unknown tool: NAME” |
| any other method | error -32601 “Method not found” |
Try it
Up to 15 XPTry the add tool
Before you code it, play the server: send arguments to add and look at the response each one deserves. Your server should produce the same kinds of answers.
The tool definition the server shares (tools/list)
{
"name": "add",
"description": "Add two integers.",
"inputSchema": {
"type": "object",
"properties": {
"a": {
"type": "integer"
},
"b": {
"type": "integer"
}
},
"required": [
"a",
"b"
],
"additionalProperties": false
}
}The server’s responseSuccess
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "Added 2 and 3."
}
],
"isError": false
}
}Applied lab: a help-desk lookup
Real teams expose narrow, auditable capabilities instead of handing an assistant broad database access. In the next exercise, a read-only get_ticket tool returns a structured result only when the ticket belongs to the verified user. Unknown and unauthorized ids produce the same error so the tool does not leak another person’s ticket existence. The official TypeScript SDK todo-board example shows the wider pattern: tools change state, resources expose it, prompts start workflows, and logs make actions observable. Our lab uses a small simulated help desk so the privacy boundary is easy to test.
Try it
Up to 15 XPTrace a private ticket lookup
Advance through the request. Predict whether the server may reveal a ticket before showing each result. The identity is assumed verified by the server for this simulation.
Predict: May the server trust a user name supplied as a tool argument?
Key takeaways
A stdio server is a loop: read a line, handle the request, write one JSON line.
Check
_metafirst, dispatch onmethod, and validate arguments before doing anything.Unknown methods →
-32601; unknown tools or missing_meta→-32602; bad tool arguments →isError: true.
Lesson quiz
5 questions · pass with 4 correct · up to 50 XP
Passing this quiz completes the lesson and keeps your streak going. Questions you miss come back in review sessions later.
Practice: build an MCP server
Write Python in the editor and run it against sample inputs. Python runs locally in your browser using a WebAssembly runtime.
Build the server
Complete handle so the server answers every request as described in the table above, printing exactly one JSON line per request with the respond helper.
- Error messages:
Missing required _meta,Unknown tool: NAME,Method not found. - For bad
addarguments, the text isInvalid arguments: a and b must be integers(arguments must be exactlyaandb, both integers, not booleans). - For a successful
add, return{"content": [{"type": "text", "text": "SUM"}], "structuredContent": {"sum": SUM}, "isError": false}.
- Discover, list and add
- Every kind of error
- Tool list
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Build a private support-ticket lookup
A help desk MCP server exposes a read-only get_ticket tool. The browser runner supplies one JSON request per line with verified_user and ticket_id; for this simulation, verified_user stands in for an identity already verified by the server. Return an MCP tool result. For a ticket owned by that user, include text content, structuredContent with ticket id, status and summary, and isError: false. For an unknown ticket or one owned by someone else, return the same not_available tool error so the caller cannot learn whether another person’s ticket exists. In a real HTTP server, derive identity from a validated token, never from tool arguments.
- Owner sees their ticket
- Other user cannot see it
- Unknown and unauthorized look the same
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Questions about this lesson
Stuck? Ask. Figured something out? Share it. Explaining is one of the best ways to learn.
Loading posts…