# modelcontextprotocol/typescript-sdk architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/typescript-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/typescript-sdk
- Repository: https://github.com/modelcontextprotocol/typescript-sdk

## Overview

#### 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: [`packages/core-internal/src/wire/bootstrap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/bootstrap.ts) (Wire version dispatcher), [`packages/server/src/server/invoke.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/invoke.ts) (Handler dispatch), [`packages/client/src/client/client.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts) (Client lifecycle), [`packages/server/src/server/streamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts) (Streamable HTTP host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol kernel"]
  node_core_public["Public core facade<br/>package entry<br/>[index.ts]"]
  node_protocol_types["Protocol types & schemas<br/>protocol model<br/>[index.ts]"]
  node_shared_kernel["Shared neutral behavior<br/>core services<br/>[protocol.ts]"]
  node_wire_bootstrap["Wire version dispatcher<br/>wire bootstrap<br/>[bootstrap.ts]"]
  node_legacy_codec["2025 legacy codec<br/>wire codec<br/>[codec.ts]"]
  node_current_codec["2026 codec<br/>wire codec<br/>[codec.ts]"]
end

subgraph group_server["Server SDK"]
  node_server_public["Server public API<br/>package entry<br/>[index.ts]"]
  node_mcp_server["McpServer lifecycle<br/>server abstraction<br/>[mcp.ts]"]
  node_server_dispatch["Handler dispatch<br/>request dispatcher<br/>[invoke.ts]"]
  node_server_http["Streamable HTTP host<br/>server transport<br/>[streamableHttp.ts]"]
  node_server_stdio["Stdio host<br/>server transport<br/>[serveStdio.ts]"]
  node_server_security["Hosting security<br/>middleware<br/>[bearerAuth.ts]"]
end

subgraph group_client["Client SDK"]
  node_client_public["Client public API<br/>package entry<br/>[index.ts]"]
  node_client_lifecycle["Client lifecycle<br/>client controller<br/>[client.ts]"]
  node_client_http["Client HTTP transport<br/>client transport<br/>[streamableHttp.ts]"]
  node_version_negotiation["Version negotiation<br/>protocol negotiation"]
end

subgraph group_integration["Integration & assurance"]
  node_runtime_adapters["HTTP runtime adapters<br/>platform adapters<br/>[streamableHttp.ts]"]
  node_codemod{{"v1-to-v2 codemod<br/>migration CLI<br/>[cli.ts]"}}
  node_conformance["Conformance harness<br/>verification"]
  node_e2e_scenarios["Cross-package E2E<br/>verification<br/>[flow.test.ts]"]
end

node_core_public -->|"exports"| node_protocol_types
node_core_public -->|"exports"| node_shared_kernel
node_shared_kernel -->|"uses wire layer"| node_wire_bootstrap
node_wire_bootstrap -.->|"legacy route"| node_legacy_codec
node_wire_bootstrap -->|"current route"| node_current_codec
node_server_public -->|"exposes"| node_mcp_server
node_mcp_server -->|"registers handlers"| node_server_dispatch
node_server_http -->|"guards requests"| node_server_security
node_server_http -->|"inbound requests"| node_server_dispatch
node_server_stdio -->|"inbound requests"| node_server_dispatch
node_server_dispatch -->|"decode and encode"| node_wire_bootstrap
node_server_dispatch -->|"validates"| node_protocol_types
node_runtime_adapters -->|"adapts platform HTTP"| node_server_http
node_client_public -->|"exposes"| node_client_lifecycle
node_client_lifecycle -->|"connects"| node_client_http
node_client_lifecycle -->|"initializes"| node_version_negotiation
node_version_negotiation -->|"selects era"| node_wire_bootstrap
node_client_lifecycle -->|"uses auth and transports"| node_shared_kernel
node_codemod -.->|"migrates consumers to"| node_server_public
node_codemod -.->|"migrates consumers to"| node_client_public
node_conformance -->|"verifies"| node_current_codec
node_e2e_scenarios -->|"exercises"| node_server_public
node_e2e_scenarios -->|"exercises"| node_client_public

click node_core_public "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/index.ts"
click node_protocol_types "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/types/index.ts"
click node_shared_kernel "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/shared/protocol.ts"
click node_wire_bootstrap "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/bootstrap.ts"
click node_legacy_codec "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/rev2025-11-25/codec.ts"
click node_current_codec "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/rev2026-07-28/codec.ts"
click node_server_public "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/index.ts"
click node_mcp_server "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts"
click node_server_dispatch "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/invoke.ts"
click node_server_http "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts"
click node_server_stdio "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/serveStdio.ts"
click node_server_security "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/middleware/bearerAuth.ts"
click node_client_public "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/index.ts"
click node_client_lifecycle "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts"
click node_client_http "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts"
click node_version_negotiation "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/versionNegotiation.ts"
click node_runtime_adapters "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/src/streamableHttp.ts"
click node_codemod "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/cli.ts"
click node_conformance "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/conformance/src/everythingServer.ts"
click node_e2e_scenarios "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/e2e/scenarios/flow.test.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_public,node_protocol_types,node_shared_kernel,node_wire_bootstrap,node_legacy_codec,node_current_codec toneBlue
class node_server_public,node_mcp_server,node_server_dispatch,node_server_http,node_server_stdio,node_server_security toneAmber
class node_client_public,node_client_lifecycle,node_client_http,node_version_negotiation toneMint
class node_runtime_adapters,node_codemod,node_conformance,node_e2e_scenarios toneRose
```

## Components

### Protocol kernel

- [Public core facade](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/index.ts): package entry · Curated public API over the internal kernel. · `packages/core/src/index.ts`
- [Protocol types & schemas](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/types/index.ts): protocol model · Capabilities, schemas, and error contracts. · `packages/core-internal/src/types/index.ts`
- [Shared neutral behavior](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/shared/protocol.ts): core services · Envelopes, transports, auth, and input-required flow. · `packages/core-internal/src/shared/protocol.ts`
- [Wire version dispatcher](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/bootstrap.ts): wire bootstrap · Selects the protocol-era codec. · `packages/core-internal/src/wire/bootstrap.ts`
- [2025 legacy codec](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/rev2025-11-25/codec.ts): wire codec · `packages/core-internal/src/wire/rev2025-11-25/codec.ts`
- [2026 codec](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core-internal/src/wire/rev2026-07-28/codec.ts): wire codec · `packages/core-internal/src/wire/rev2026-07-28/codec.ts`

### Server SDK

- [Server public API](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/index.ts): package entry · `packages/server/src/index.ts`
- [McpServer lifecycle](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts): server abstraction · Owns capability registration and lifecycle. · `packages/server/src/server/mcp.ts`
- [Handler dispatch](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/invoke.ts): request dispatcher · Builds and invokes validated capability handlers. · `packages/server/src/server/invoke.ts`
- [Streamable HTTP host](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts): server transport · Maintains request, stream, and session context. · `packages/server/src/server/streamableHttp.ts`
- [Stdio host](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/serveStdio.ts): server transport · `packages/server/src/server/serveStdio.ts`
- [Hosting security](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/middleware/bearerAuth.ts): middleware · Bearer, OAuth metadata, origin, and Host validation. · `packages/server/src/server/middleware/bearerAuth.ts`

### Client SDK

- [Client public API](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/index.ts): package entry · `packages/client/src/index.ts`
- [Client lifecycle](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts): client controller · Coordinates initialization, calls, and notifications. · `packages/client/src/client/client.ts`
- [Client HTTP transport](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts): client transport · Connects through Streamable HTTP. · `packages/client/src/client/streamableHttp.ts`
- [Version negotiation](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/versionNegotiation.ts): protocol negotiation · `packages/client/src/client/versionNegotiation.ts`

### Integration & assurance

- [HTTP runtime adapters](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/src/streamableHttp.ts): platform adapters · Node, Express, Fastify, and Hono hosting adapters. · `packages/middleware/node/src/streamableHttp.ts`
- [v1-to-v2 codemod](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/cli.ts): migration CLI · AST-based migration tooling. · `packages/codemod/src/cli.ts`
- [Conformance harness](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/conformance/src/everythingServer.ts): verification · Protocol conformance validation. · `test/conformance/src/everythingServer.ts`
- [Cross-package E2E](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/e2e/scenarios/flow.test.ts): verification · `test/e2e/scenarios/flow.test.ts`

## Connections

- 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
