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
• Getting Started
• 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. It runs on Node.js, Bun, and Deno, 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

Tool and prompt schemas use Standard Schema — bring Zod v4, Valibot, ArkType, or any compatible library.

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
# or
bun add @modelcontextprotocol/server
# or
deno add npm:@modelcontextprotocol/server

Client

npm install @modelcontextprotocol/client
# or
bun add @modelcontextprotocol/client
# or
deno add npm:@modelcontextprotocol/client

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

Getting Started

Here is what an MCP server looks like. This minimal example exposes a single greet tool over stdio:

import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });

server.registerTool(
  'greet',
  {
    description: 'Greet someone by name',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  }),
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

Ready to build something real? Follow the step-by-step quickstart tutorials:

• Build a weather server — server quickstart
• Build an LLM-powered chatbot — client quickstart

The complete code for each tutorial is in examples/server-quickstart/ and examples/client-quickstart/. For more advanced runnable examples, see:

• examples/server/README.md — server examples index
• examples/client/README.md — client examples index

Documentation

• Server Guide — building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment
• Client Guide — building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
• FAQ — frequently asked questions and troubleshooting
• API docs
• MCP documentation
• MCP specification

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.