typescript-sdk

# MCP TypeScript SDK   <details> <summary>Table of Contents</summary> - [Overview](#overview) - [Installation](#installation) - [Quick Start](#quick-start) - [Core Concepts](#core-concepts) - [Examples](#examples) - [Documentation](#documentation) - [Contributing](#contributing) - [License](#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](https://modelcontextprotocol.io/specification/draft), 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 ```bash 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): ```bash npm install ``` 2. **Run the example Streamable HTTP server**: ```bash npx tsx src/examples/server/simpleStreamableHttp.ts ``` 3. **Run the interactive client in another terminal**: ```bash 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](docs/server.md) and [docs/client.md](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](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](docs/server.md#tools-resources-and-prompts), with runnable implementations in [`simpleStreamableHttp.ts`](src/examples/server/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](docs/capabilities.md) Key example servers include: - [`toolWithSampleServer.ts`](src/examples/server/toolWithSampleServer.ts) - [`elicitationFormExample.ts`](src/examples/server/elicitationFormExample.ts) - [`elicitationUrlExample.ts`](src/examples/server/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](docs/client.md), including: - Interactive Streamable HTTP client ([`simpleStreamableHttp.ts`](src/examples/client/simpleStreamableHttp.ts)) - Streamable HTTP client with SSE fallback ([`streamableHttpWithSseFallbackClient.ts`](src/examples/client/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](docs/faq.md) for details on supported Node.js versions and how to polyfill `globalThis.crypto` when running on older Node.js runtimes. ## E