MCP TypeScript SDK

[!IMPORTANT] This is the main branch which contains v2 of the SDK (currently in development, pre-alpha).

We anticipate a stable v2 release in Q1 2026. Until then, v1.x remains the recommended version for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade.

For v1 documentation, see the V1 API docs. For v2 API docs, see /v2/.

Table of Contents

• Overview
• Packages
• Installation
• Quick Start (runnable examples)
• Documentation
• Contributing
• License

Overview

The Model Context Protocol (MCP) allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.

This repository contains the TypeScript SDK implementation of the MCP specification and ships:

• MCP server libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)
• MCP client libraries (transports, high-level helpers, OAuth helpers)
• Optional middleware packages for specific runtimes/frameworks (Express, Hono, Node.js HTTP)
• Runnable examples (under examples/)

Packages

This monorepo publishes split packages:

• @modelcontextprotocol/server: build MCP servers
• @modelcontextprotocol/client: build MCP clients

Both packages have a required peer dependency on zod for schema validation. The SDK uses Zod v4.

Middleware packages (optional)

The SDK also publishes small "middleware" packages under packages/middleware/ that help you wire MCP into a specific runtime or web framework.

They are intentionally thin adapters: they should not introduce new MCP functionality or business logic. See packages/middleware/README.md for details.

• @modelcontextprotocol/node: Node.js Streamable HTTP transport wrapper for IncomingMessage / ServerResponse
• @modelcontextprotocol/express: Express helpers (app defaults + Host header validation)
• @modelcontextprotocol/hono: Hono helpers (app defaults + JSON body parsing hook + Host header validation)

Installation

Server

npm install @modelcontextprotocol/server zod

Client

npm install @modelcontextprotocol/client zod

Optional middleware packages

The SDK also publishes optional “middleware” packages that help you wire MCP into a specific runtime or web framework (for example Express, Hono, or Node.js http).

These packages are intentionally thin adapters and should not introduce additional MCP features or business logic. See packages/middleware/README.md for details.

# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:
npm install @modelcontextprotocol/node

# Express integration:
npm install @modelcontextprotocol/express express

# Hono integration:
npm install @modelcontextprotocol/hono hono

Quick Start (runnable examples)

The runnable examples live under examples/ and are kept in sync with the docs.

1. Install dependencies (from repo root):

pnpm install

2. Run a Streamable HTTP example server:

pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts

Alternatively, from within the example package:

cd examples/server
pnpm tsx src/simpleStreamableHttp.ts

3. Run the interactive client in another terminal:

pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts

Alternatively, from within the example package:

cd examples/client
pnpm tsx src/simpleStreamableHttp.ts

Next steps:

• Server examples index: examples/server/README.md
• Client examples index: examples/client/README.md
• Guided walkthroughs: docs/server.md and docs/client.md

Documentation

• Local SDK docs:
  • docs/server.md – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns.
  • docs/client.md – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
  • docs/faq.md – frequently asked questions and troubleshooting
• External references:
  • SDK API documentation
  • Model Context Protocol documentation
  • MCP Specification
  • Example Servers

Building docs locally

To generate the API reference documentation locally:

pnpm docs          # Generate V2 docs only (output: tmp/docs/)
pnpm docs:multi    # Generate combined V1 + V2 docs (output: tmp/docs-combined/)

The docs:multi script checks out both the v1.x and main branches via git worktrees, builds each, and produces a combined site with V1 docs at the root and V2 docs under /v2/.

v1 (legacy) documentation and fixes

If you are using the v1 generation of the SDK, the v1 API documentation is available at https://ts.sdk.modelcontextprotocol.io/. The v1 source code and any v1-specific fixes live on the long-lived v1.x branch. V2 API docs are at /v2/.

Contributing

Issues and pull requests are welcome on GitHub at https://github.com/modelcontextprotocol/typescript-sdk.

License

This project is licensed under the Apache License 2.0 for new contributions, with existing code under MIT. See the LICENSE file for details.