MCP TypeScript SDK

The MCP TypeScript SDK is the official, reference implementation of the Model Context Protocol (MCP) for Node.js, Bun, and Deno. It gives developers a single package for building both MCP servers that expose tools, resources, and prompts to LLM applications, and MCP clients that can connect to any compliant server over stdio or Streamable HTTP transports.

Under the hood the SDK layers a high-level McpServer/client API for common cases over a low-level Protocol/Server implementation for advanced control, all built on JSON-RPC 2.0 messaging with Zod-based schema validation. With tens of millions of weekly downloads, it is the reference implementation most MCP servers and clients in the wild are built on.

What You Get

• A high-level McpServer class for registering tools, resources, and prompts with a few lines of code
• A full-featured MCP client with support for stdio, Streamable HTTP, and legacy HTTP+SSE transports
• Built-in OAuth 2.0 client and server auth helpers (via jose and pkce-challenge) for remote server authentication
• Zod-based (v3 or v4) schema validation for tool inputs/outputs, resource templates, and prompt arguments
• Experimental support for long-running tasks, sampling, and elicitation capabilities from the latest MCP spec

Common Use Cases

• Exposing an internal API, database, or SaaS product as tools an LLM agent (e.g. Claude, an IDE assistant) can call
• Building a remote MCP server that AI clients connect to over Streamable HTTP with OAuth-protected access
• Writing an MCP client inside an agent framework or IDE plugin to discover and invoke tools from any compliant server
• Bridging existing REST/GraphQL services into the MCP tool/resource/prompt model for LLM consumption

Under The Hood

Architecture — The SDK layers a high-level API over a low-level protocol core. src/shared/protocol.ts (~1700 lines) implements a Protocol base class handling JSON-RPC request/response correlation, progress notifications, cancellation, and an optional task-tracking layer (experimental/tasks) for long-running operations; both Client (src/client/index.ts) and Server (src/server/index.ts) extend it. On top of that, McpServer (src/server/mcp.ts, ~1550 lines) provides the ergonomic surface most users touch — registerTool/registerResource/registerPrompt — internally translating registrations into the low-level request handlers and delegating transport I/O to pluggable Transport implementations (stdio.ts, streamableHttp.ts, sse.ts, webStandardStreamableHttp.ts). This separation means advanced users can drop to the Server/Protocol layer for custom notification handling while most consumers never leave the McpServer façade.

Tech Stack — Pure TypeScript (Node >=18, also runs on Bun/Deno), built to dual ESM/CJS output via separate tsc passes (tsconfig.json/tsconfig.cjs.json) and type-checked with tsgo. Runtime dependencies are deliberately small and mostly server-transport related: express and hono route helpers, cors, express-rate-limit, eventsource/eventsource-parser for SSE, jose and pkce-challenge for OAuth, ajv/ajv-formats/json-schema-typed for JSON Schema handling, and zod-to-json-schema for converting Zod schemas to the wire format. zod (v3.25+ or v4) is a required peer dependency, with a compatibility shim (zod-compat.ts, zod-json-schema-compat.ts) so both major versions interoperate.

Code Quality — 48 *.test.ts files sit alongside ~87 source files, run through Vitest (npm test), plus a dedicated conformance test suite (test/conformance/) that runs generated server/client behavior against a spec baseline (conformance-baseline.yml) — an unusually rigorous check for a protocol SDK. Linting is ESLint + Prettier (npm run lint), typechecking is a separate tsgo --noEmit step, and a check script chains both. Errors are represented as typed McpError instances with protocol-defined ErrorCodes rather than thrown strings, and Zod’s safeParse/safeParseAsync are used throughout instead of exception-driven validation.

API Design — The two-tier design (low-level Server/Protocol vs. high-level McpServer) is deliberately reminiscent of how Express separates raw http handling from route sugar, and it pays off in a genuinely low-boilerplate quick start: a working tool-serving server is a handful of registerTool calls plus a transport connect(). Documentation is split into task-oriented guides (docs/server.md, docs/client.md) rather than pure API reference, and runnable examples under src/examples/ (stdio, Streamable HTTP, OAuth) are exercised as part of docs:examples — so the docs can’t silently drift from working code.