How modelcontextprotocol/typescript-sdk works
Purpose and package surface
This pnpm TypeScript monorepo implements the MCP 2026-07-28 SDK (v2 beta): reusable client and server libraries rather than an application. Primary published entry points are packages/server/src/index.ts, packages/client/src/index.ts, and the public core facade packages/core/src/index.ts. It supports Node.js, Bun, Deno, and worker-style runtimes, with Standard Schema-compatible validation.
Protocol foundation and version boundary
packages/core-internal is the shared protocol kernel, while packages/core exposes its curated public surface. Protocol types, capabilities, schemas, and error shapes live in packages/core-internal/src/types/; shared neutral behavior (envelopes, transports, auth, input-required flow) is in packages/core-internal/src/shared/. The wire layer dispatches and encodes per protocol era, explicitly separating legacy 2025-11-25 compatibility from 2026-07-28 behavior:
• packages/core-internal/src/wire/bootstrap.ts
• packages/core-internal/src/wire/rev2025-11-25/codec.ts
• packages/core-internal/src/wire/rev2026-07-28/codec.ts
Server construction and dispatch
The server package turns registered MCP capabilities—tools, resources, prompts, completion, subscriptions, sampling, elicitation—into request handlers. McpServer/server abstractions own registration and lifecycle; invocation and handler construction isolate request dispatch from transport plumbing. High-level server entry points include:
• packages/server/src/server/mcp.ts
• packages/server/src/server/server.ts
• packages/server/src/server/createMcpHandler.ts
• packages/server/src/server/invoke.ts
Inbound requests are classified/decoded through core, matched to declared handlers, schema-validated, invoked with request context/state, then encoded as JSON-RPC results, notifications, or errors.
Server transports, state, and security
Server hosting supports stdio and Streamable HTTP. HTTP handling creates per-request transport context, manages streaming/session behavior, and preserves request state; stdio is a separate process-stream adapter. Key boundaries:
• packages/server/src/server/streamableHttp.ts
• packages/server/src/server/perRequestTransport.ts
• packages/server/src/server/requestStateCodec.ts
• packages/server/src/server/serveStdio.ts
Security at the hosting boundary includes bearer-token checks, OAuth protected-resource metadata, origin validation, and Host-header validation in packages/server/src/server/middleware/.
Client connection and request flow
The client package connects to MCP servers over stdio, SSE, or Streamable HTTP, negotiates protocol versions, manages authentication, and exposes higher-level calls/listening. Its central control path is client lifecycle → transport connection/probe → initialize/version negotiation → request/response correlation and notifications. Core modules are:
• packages/client/src/client/client.ts
• packages/client/src/client/streamableHttp.ts
• packages/client/src/client/stdio.ts
• packages/client/src/client/versionNegotiation.ts
Client-side middleware, response caching, OAuth/token handling, and cross-app access are additive layers around this transport/request engine.
Runtime adapters and external integrations
Thin packages adapt server HTTP behavior to platform APIs without adding MCP semantics: Node HTTP (packages/middleware/node/src/streamableHttp.ts), Express (packages/middleware/express/src/express.ts), Fastify, and Hono. Browser, Node, and Workerd shims separate runtime-specific dependencies in packages/client/src/shimsBrowser.ts, packages/client/src/shimsNode.ts, and packages/server/src/shimsWorkerd.ts. OAuth/bearer authorization integrates with external authorization servers and protected-resource metadata; no application database or LLM provider is required by the SDK.
Migration, verification, and documentation
The codemod package provides AST-based v1-to-v2 migration via packages/codemod/src/cli.ts and packages/codemod/src/migrations/v1-to-v2/. Protocol correctness is anchored by versioned wire/schema corpora in packages/core-internal/test/corpus/, cross-package E2E scenarios in test/e2e/scenarios/, and conformance harnesses in test/conformance/src/. VitePress documentation and runnable examples are integration-facing entry points at docs/.vitepress/config.mts and examples/.
Main entry points: bootstrap.ts Wire version dispatcher · invoke.ts Handler dispatch · client.ts Client lifecycle · streamableHttp.ts Streamable HTTP host
Components 20
Protocol kernel
- Public core facade · Curated public API over the internal kernel.
packages/core/src/index.ts - Protocol types & schemas · Capabilities, schemas, and error contracts.
packages/core-internal/src/types/index.ts - Shared neutral behavior · Envelopes, transports, auth, and input-required flow.
packages/core-internal/src/shared/protocol.ts - Wire version dispatcher · Selects the protocol-era codec.
packages/core-internal/src/wire/bootstrap.ts - 2025 legacy codec
packages/core-internal/src/wire/rev2025-11-25/codec.ts - 2026 codec
packages/core-internal/src/wire/rev2026-07-28/codec.ts
Server SDK
- Server public API
packages/server/src/index.ts - McpServer lifecycle · Owns capability registration and lifecycle.
packages/server/src/server/mcp.ts - Handler dispatch · Builds and invokes validated capability handlers.
packages/server/src/server/invoke.ts - Streamable HTTP host · Maintains request, stream, and session context.
packages/server/src/server/streamableHttp.ts - Stdio host
packages/server/src/server/serveStdio.ts - Hosting security · Bearer, OAuth metadata, origin, and Host validation.
packages/server/src/server/middleware/bearerAuth.ts
Client SDK
- Client public API
packages/client/src/index.ts - Client lifecycle · Coordinates initialization, calls, and notifications.
packages/client/src/client/client.ts - Client HTTP transport · Connects through Streamable HTTP.
packages/client/src/client/streamableHttp.ts - Version negotiation
packages/client/src/client/versionNegotiation.ts
Integration & assurance
- HTTP runtime adapters · Node, Express, Fastify, and Hono hosting adapters.
packages/middleware/node/src/streamableHttp.ts - v1-to-v2 codemod · AST-based migration tooling.
packages/codemod/src/cli.ts - Conformance harness · Protocol conformance validation.
test/conformance/src/everythingServer.ts - Cross-package E2E
test/e2e/scenarios/flow.test.ts
Connections 23
- Public core facade → Protocol types & schemas: exports
- Public core facade → Shared neutral behavior: exports
- Shared neutral behavior → Wire version dispatcher: uses wire layer
- Wire version dispatcher → 2025 legacy codec: legacy route
- Wire version dispatcher → 2026 codec: current route
- Server public API → McpServer lifecycle: exposes
- McpServer lifecycle → Handler dispatch: registers handlers
- Streamable HTTP host → Hosting security: guards requests
- Streamable HTTP host → Handler dispatch: inbound requests
- Stdio host → Handler dispatch: inbound requests
- Handler dispatch → Wire version dispatcher: decode and encode
- Handler dispatch → Protocol types & schemas: validates
- HTTP runtime adapters → Streamable HTTP host: adapts platform HTTP
- Client public API → Client lifecycle: exposes
- Client lifecycle → Client HTTP transport: connects
- Client lifecycle → Version negotiation: initializes
- Version negotiation → Wire version dispatcher: selects era
- Client lifecycle → Shared neutral behavior: uses auth and transports
- v1-to-v2 codemod → Server public API: migrates consumers to
- v1-to-v2 codemod → Client public API: migrates consumers to
- Conformance harness → 2026 codec: verifies
- Cross-package E2E → Server public API: exercises
- Cross-package E2E → Client public API: exercises