MCP TypeScript SDK !NPM Version !MIT licensed

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

``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 and
docs/client.md.

Core Concepts

$3

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.

$3

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

$3

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

$3

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

$3

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.

$3

| Scenario | Description | Example file(s) | Related docs |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Streamable HTTP server (stateful) | Feature-rich server with tools, resources, prompts, logging, tasks, sampling, and optional OAuth. | simpleStreamableHttp.ts | server.md, capabilities.md |
| Streamable HTTP server (stateless) | No session tracking; good for simple API-style servers. | simpleStatelessStreamableHttp.ts | server.md |
| JSON response mode (no SSE) | Streamable HTTP with JSON responses only and limited notifications. | jsonResponseStreamableHttp.ts | server.md |
| Server notifications over Streamable HTTP | Demonstrates server-initiated notifications using SSE with Streamable HTTP. | standaloneSseWithGetStreamableHttp.ts | server.md |
| Deprecated HTTP+SSE server | Legacy HTTP+SSE transport for backwards-compatibility testing. | simpleSseServer.ts | server.md |
| Backwards-compatible server (Streamable HTTP + SSE) | Single server that supports both Streamable HTTP and legacy SSE clients. | sseAndStreamableHttpCompatibleServer.ts | server.md |
| Form elicitation server | Uses form elicitation to collect non-sensitive user input. | elicitationFormExample.ts | capabilities.md |
| URL elicitation server | Demonstrates URL-mode elicitation in an OAuth-protected server. | elicitationUrlExample.ts | capabilities.md |
| Sampling and tasks server | Combines tools, logging, sampling, and experimental task-based execution. | toolWithSampleServer.ts | capabilities.md |
| OAuth demo authorization server | In-memory OAuth provider used with the example servers. | demoInMemoryOAuthProvider.ts | server.md |

$3

| Scenario | Description | Example file(s) | Related docs |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Interactive Streamable HTTP client | CLI client that exercises tools, resources, prompts, elicitation, and tasks. | simpleStreamableHttp.ts | client.md |
| Backwards-compatible client (Streamable HTTP → SSE) | Tries Streamable HTTP first, then falls back to SSE on 4xx responses. | streamableHttpWithSseFallbackClient.ts | client.md, server.md |
| SSE polling client | Polls a legacy SSE server and demonstrates notification handling. | ssePollingClient.ts | client.md |
| Parallel tool calls client | Shows how to run multiple tool calls in parallel. | parallelToolCallsClient.ts | client.md |
| Multiple clients in parallel | Demonstrates connecting multiple clients concurrently to the same server. | multipleClientsParallel.ts | client.md |
| OAuth clients | Examples of client_credentials (basic and private_key_jwt) and reusable providers. | simpleOAuthClient.ts, simpleOAuthClientProvider.ts, simpleClientCredentials.ts | client.md |
| URL elicitation client | Works with the URL elicitation server to drive secure browser flows. | elicitationUrlExample.ts | capabilities.md |

Shared utilities:

- In-memory event store for resumability: inMemoryEventStore.ts (see server.md).

For more details on how to run these examples (including recommended commands and deployment diagrams), see src/examples/README.md`.

Documentation

- Local SDK docs:
- docs/server.md – building and running MCP servers, transports, tools/resources/prompts, CORS, DNS rebinding, and multi-node deployment.
- docs/client.md – using the high-level client, transports, backwards compatibility, and OAuth helpers.
- docs/capabilities.md – sampling, elicitation (form and URL), and experimental task-based execution.
- docs/faq.md – environment and troubleshooting FAQs (including Node.js Web Crypto support).
- External references:
- Model Context Protocol documentation
- MCP Specification
- Example Servers

Contributing

Issues and pull requests are welcome on GitHub at .

License

This project is licensed under the MIT License—see the LICENSE file for details.