You want to build an MCP server in TypeScript. What package do you use and how does it handle schemas?
Install `@modelcontextprotocol/sdk` from npm. Zod schemas give runtime validation, TS types, and JSON Schema for the LLM. Ships stdio and streamable HTTP transports.
Imagine you have a small TypeScript program with a few functions you want an AI to call. The TypeScript MCP SDK is a library you install with one npm command. You register each function with a Zod schema describing its arguments (Zod is just TypeScript code), and the SDK turns your program into a server any MCP host can connect to. Because TypeScript runs on Node, Bun, Deno, and Cloudflare Workers, this same SDK is how most cloud-hosted MCP servers are built.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
TypeScript is the lingua franca of MCP hosts. Claude Desktop is TypeScript. Cursor is TypeScript. Continue is TypeScript. A huge share of community servers, especially the ones that need to run in the cloud or at the edge, are TypeScript too. The official TypeScript MCP SDK is the substrate underneath nearly all of that.
This deep dive covers the package itself, the dual server and client API, the Zod-driven schema story that defines the SDK's ergonomics, the transports (including which one is deprecated), and why Cloudflare Workers became the default cloud target for hosted MCP servers.
Package, scope, and where it lives
The package is @modelcontextprotocol/sdk on npm. The @modelcontextprotocol scope is owned by the official GitHub org, so any install from that scope is first-party. Install with npm install @modelcontextprotocol/sdk, or pnpm/yarn/bun equivalents.
The repository is github.com/modelcontextprotocol/typescript-sdk, one of the first-party SDK repos under the org (the others are python-sdk and a growing set of community to official language SDKs). The package is ESM with TypeScript types, so any modern toolchain (TS 5+, Node 20+, Bun 1.0+, Deno) consumes it directly.
What you get on install: server-side classes (McpServer, low-level Server), client-side classes (Client), transport classes (StdioServerTransport, StreamableHTTPServerTransport, the deprecated SSEServerTransport), full TypeScript types for every protocol message, and JSON Schema utilities. The package is well under 1 MB with a small dependency footprint.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Cloudflare Workers MCP servers (the GitHub MCP server's hosted variant, SaaS vendor servers) are built on this SDK and deployed via Cloudflare's workers-mcp tooling with automatic OAuth.
- VS Code extensions like Continue use the Client API from the same package to connect to MCP servers the user has configured.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow does the Zod-to-JSON-Schema conversion work inside the SDK?
The SDK uses Zod's schema introspection (or zod-to-json-schema internally) to walk the Zod type and emit an equivalent JSON Schema. The conversion runs once per tool registration, so the schema cost is amortized across all calls.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Searching npm for `mcp` or `mcp-sdk` instead of the scoped package `@modelcontextprotocol/sdk`. The scope signals it is the official org-owned SDK.
60 second bullets to scan on the way to the call.
The scoped npm package name and install command.
The GitHub repo that owns the SDK.
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.