@mcp-use/modelcontextprotocol-sdk weekly downloads statistics

MCP TypeScript SDK

<details> <summary>Table of Contents</summary>

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

</details>

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 full 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

npm install @modelcontextprotocol/sdk zod

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):

   npm install
   

2. Run the example Streamable HTTP server:

   npx tsx src/examples/server/simpleStreamableHttp.ts
   

3. Run the interactive client in another terminal:

   npx tsx src/examples/client/simpleStreamableHttp.ts
   

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…