Repository files navigation

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

npm install @modelcontextprotocol/sdk zod

This SDK has arequired peer dependency onzod for schema validation. The SDK internally imports fromzod/v4, but maintains backwards compatibility with projects using Zod v3.25 or later. You can use either API in your code by importing fromzod/v3 orzod/v4:

To see the SDK in action end-to-end, start from the runnable examples insrc/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.), seedocs/server.md anddocs/client.md.

An MCP server is typically created withMcpServer 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 undersrc/examples/server and are documented indocs/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, includingResourceTemplate, completions, and display-name metadata, are covered indocs/server.md, with runnable implementations insimpleStreamableHttp.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:

• docs/capabilities.md

Key example servers include:

• toolWithSampleServer.ts
• elicitationFormExample.ts
• elicitationUrlExample.ts

The high-levelClient class connects to MCP servers over different transports and exposes helpers likelistTools,callTool,listResources,readResource,listPrompts, andgetPrompt.

Runnable clients live undersrc/examples/client and are described indocs/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 inauth-extensions.ts viajose) rely on the Web Crypto API exposed asglobalThis.crypto.

Seedocs/faq.md for details on supported Node.js versions and how to polyfillglobalThis.crypto when running on older Node.js runtimes.

The SDK ships runnable examples undersrc/examples. Use these tables to find the scenario you care about and jump straight to the corresponding code and docs.

Shared utilities:

• In-memory event store for resumability:inMemoryEventStore.ts (seeserver.md).

For more details on how to run these examples (including recommended commands and deployment diagrams), seesrc/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 athttps://github.com/modelcontextprotocol/typescript-sdk.

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