Building an MCP Server in TypeScript — Tool Use, Function Calling & MCP

Lesson 16 built a working MCP server in Python: FastMCP, Pydantic models, decorators, a docstring that doubled as the tool's description. The protocol that server speaks — JSON-RPC over stdio, tools with a name and a JSON-Schema input, structured results — is identical no matter which SDK emits it. This lesson builds the same tickets server again, this time in TypeScript, and the point is not to relearn what a tool or a transport is.

The point is what genuinely changes when the implementation language changes. Zod replaces Pydantic as the input contract, but with a sharper edge: `z.infer` derives the handler's parameter type directly from the schema object, so there is no second place for the type to quietly disagree with the validation. The TypeScript SDK does not read your handler's JSDoc comment the way FastMCP reads a Python docstring — description is a field you set explicitly, or it ships empty. And a `npm run build` step exists that Python's interpreter never gives you: a schema and a handler that no longer agree is a compile error, not a runtime surprise months later.

By the end of this lesson you will have written `SearchTicketsInputSchema` as a Zod object and derived its TypeScript type from it, registered a tool with `registerTool` carrying an explicit description and all four annotation hints, returned both `content` and `structuredContent` from the same handler, wired stdio transport with the `console.error` logging rule strictly observed, and compiled and inspected the result with the official tools rather than guessing at correctness.

Analogy🏏Cricket

🏏 Think of it like cricket: In August, the Indian team plays a Test series in England, then flies to South Africa for a white-ball series three weeks later — same batting lineup, same core technique, two very different disciplines. In the Test nets at Edgbaston, every technical flaw gets found and fixed before the first ball of the match: the batting coach has Shubman Gill face 200 throwdowns until his trigger movement against the moving ball is locked in, because once the Test starts there's no going back to fix a flawed technique mid-innings — you either survive the ball or you don't. In the white-ball series that follows, the same players adapt on the fly: a shot that doesn't work gets abandoned mid-over, in the moment, in front of the crowd, and the correction happens live rather than in the nets. Building the same MCP server in Python and then in TypeScript is this same pair of tours with the same squad. The protocol, the tools, the intent — identical, like the batting lineup. What changes is when the flaw gets caught: TypeScript's compiler is the Edgbaston nets, refusing to let a schema and a handler drift apart before a single request is ever served, while Python's duck typing plays the white-ball game, discovering a mismatch only when the ball is actually bowled at runtime. Neither discipline is wrong — but you prepare very differently for each one.