Model Context Protocol implementation for TypeScript
npm install @modelcontextprotocol/sdkTable of Contents
- Overview
- Installation
- Quick Start
- Core Concepts
- Examples
- Documentation
- Contributing
- License
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
``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:
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.
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 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.
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:
Key example servers include:
- toolWithSampleServer.ts
- elicitationFormExample.ts
- elicitationUrlExample.ts
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
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.
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.
| 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 |
| 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`.
- 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
Issues and pull requests are welcome on GitHub at
This project is licensed under the MIT License—see the LICENSE file for details.