@modelcontextprotocol/sdk weekly downloads statistics

MCP TypeScript SDK

This is v1.x of the MCP TypeScript SDK, the maintenance line. It implements the MCP spec up to 2025-11-25. Support for the 2026-07-28 spec is not planned for v1.x: it is in v2, the current stable release, which ships as separate packages, @modelcontextprotocol/server and @modelcontextprotocol/client. See the v2 documentation and the migration guide.

Staying on v1.x? It continues to receive bug fixes and security updates for at least six months after the v2 release (2026-07-27). The v1 documentation is at .

Table of Contents

• Overview • Installation • Quick Start • Core Concepts • Examples • Documentation • Contributing • License

Overview

The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This TypeScript SDK implements the 2025-11-25 MCP specification, making it easy to:

• Create MCP servers that expose resources, prompts and tools • Build MCP clients that can connect to any MCP server • Use standard transports like stdio and Streamable HTTP

Installation

This SDK has a required peer dependency on zod for schema validation. The SDK internally imports from zod/v4, but maintains backwards compatibility with projects using Zod v3.25 or later. You can use either API in your code by importing from zod/v3 or zod/v4:

Quick Start

To see the SDK in action end-to-end, start from the runnable examples in src/examples:

1. Install dependencies (from the SDK repo root):

2. Run the example Streamable HTTP server:

3. Run the interactive client in another terminal:

This pair of examples demonstrates tools, resources, prompts, sampling, elicitation, tasks and logging. For a guided walkthrough and variations (stateless servers, JSON-only responses, SSE compatibility, OAuth, etc.), see docs/server.md and docs/client.md.

Core Concepts

Servers and transports

An MCP server is typically created with McpServer and connected to a transport such as Streamable HTTP or stdio. The SDK supports:

• Streamable HTTP for remote servers (recommended). • HTTP + SSE for backwards compatibility only. • stdio for local, process-spawned integrations.

Runnable server examples live under src/examples/server and are documented in docs/server.md.

Tools, resources, prompts

• Tools let LLMs ask your server to take actions (computation, side effects, network calls). • Resources expose read-only data that clients can surface to users or models. • Prompts are reusable templates that help users talk to models in a consistent way.

The detailed APIs, including ResourceTemplate, completions, and display-name metadata, are covered in docs/server.md, with runnable implementations in simpleStreamableHttp.ts.

Capabilities: sampling, elicitation, and tasks

The SDK includes higher-level capabilities for richer workflows:

• Sampling: server-side tools can ask connected clients to run LLM completions. • Form elicitation: tools can request non-sensitive input via structured forms. • URL elicitation: servers can ask users to complete secure flows in a browser (e.g., API key entry, payments, OAuth). • Tasks (experimental): long-running tool calls can be turned into tasks that you poll or resume later.

Conceptual overviews and links to runnable examples are in:

• docs/capabilities.md

Key example servers include:

• toolWithSampleServer.ts • elicitationFormExample.ts • elicitationUrlExample.ts

Clients

The high-level Client class connects to MCP servers over different transports and exposes helpers like listTools, callTool, listResources, readResource, listPrompts, and getPrompt.

Runnable clients live under src/examples/client and are described in docs/client.md, including:

• Interactive Streamable HTTP client (simpleStreamableHttp.ts) • Streamable HTTP client with SSE fallback (streamableHttpWithSseFallbackClient.ts) • OAuth-enabled clients and polling/parallel examples

Node.js Web Crypto (globalThis.crypto) compatibility

Some parts of the SDK (for example, JWT-based client authentication in auth-extensions.ts via jose) rely on the Web Crypto API exposed as globalThis.crypto.

See docs/faq.md for details on supported Node.js versions and how to polyfill globalThis.crypto when running on older Node.js runtimes.

Examples

The SDK ships runnable examples under src/examples. Use these tables to find the scenario you care about and jump straight to the corresponding code and docs.

Server examples

| Scenario | Description | Example file(s) | Related docs |…

Description from the npm listing.