MCP TypeScript SDK

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

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

Client examples

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 https://github.com/modelcontextprotocol/typescript-sdk.

License

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