# MCP TypeScript SDK

> The official TypeScript SDK for the Model Context Protocol (MCP): build MCP servers and clients on Node.js, Bun, Deno, and Workers. This is the v2 beta documentation, tracking the 2026-07-28 spec revision.

Every page below is also served as plain markdown at its `.md` URL — fetch any page directly.

## Overview

- [MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/v2/index.md): The Model Context Protocol (MCP) is an open standard that connects AI applications to the systems where your data and tools live.

## Get started

- [Build a server](https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-server.md): Build an MCP server — a program that exposes tools a model can call — and call its one tool, a US weather-alert lookup, from a client.
- [Plug into a real host](https://ts.sdk.modelcontextprotocol.io/v2/get-started/real-host.md): A host is an application with a model in it — VS Code with Copilot, Claude Code, Cursor.
- [Build a client](https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-client.md): Build an MCP client — the program that launches a server, lists its tools, and calls them — against the weather server from Build your first server.
- [Packages](https://ts.sdk.modelcontextprotocol.io/v2/get-started/packages.md): The SDK is published as nine npm packages.
- [Examples](https://ts.sdk.modelcontextprotocol.io/v2/get-started/examples.md): Looking for code that shows how to do something specific?

## Servers

- [Tools](https://ts.sdk.modelcontextprotocol.io/v2/servers/tools.md): A tool is an action a connected client — and the model driving it — can invoke on your server.
- [Resources](https://ts.sdk.modelcontextprotocol.io/v2/servers/resources.md): A resource is read-only data — a file, a database row, a rendered report — that a connected client lists, reads, and attaches as context for the model.
- [Prompts](https://ts.sdk.modelcontextprotocol.io/v2/servers/prompts.md): A prompt is a message template a connected client invokes by name.
- [Completion](https://ts.sdk.modelcontextprotocol.io/v2/servers/completion.md): Completion is server-side autocomplete for prompt arguments and resource template variables: the client sends the partial value the user has typed so far, your callback returns the matching suggestions.
- [Logging, progress, cancellation](https://ts.sdk.modelcontextprotocol.io/v2/servers/logging-progress-cancellation.md): Every handler receives a context as its second argument; the request-scoped helpers — progress, logging, and the cancellation signal — live on ctx.mcpReq.
- [Elicitation](https://ts.sdk.modelcontextprotocol.io/v2/servers/elicitation.md): A tool handler asks the end user a question mid-call with ctx.mcpReq.elicitInput — the connected client puts the question in front of them and the promise resolves with their answer.
- [Sampling (sunset)](https://ts.sdk.modelcontextprotocol.io/v2/servers/sampling.md): Sampling routes an LLM call through the connected client: a tool handler sends a prompt, the host runs it through a model it controls, and the handler resumes with the completion.
- [Input required](https://ts.sdk.modelcontextprotocol.io/v2/servers/input-required.md): An input_required result is how a tools/call, prompts/get, or resources/read handler asks the connected client for input mid-call: the handler returns the embedded requests, the client answers them and retries the…
- [Notifications](https://ts.sdk.modelcontextprotocol.io/v2/servers/notifications.md): A notification is a one-way message your server pushes to a connected client; change notifications tell clients that a list or a resource they cached is stale.
- [Errors](https://ts.sdk.modelcontextprotocol.io/v2/servers/errors.md): A tool error is a successful JSON-RPC result with isError: true that the model reads and recovers from.

## Serving

- [stdio](https://ts.sdk.modelcontextprotocol.io/v2/serving/stdio.md): A host that launches your server as a local child process talks to it over stdio: JSON-RPC requests arrive on stdin, responses leave on stdout.
- [HTTP](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.md): To host one MCP endpoint that many clients connect to, serve your factory over Streamable HTTP.
- [Express](https://ts.sdk.modelcontextprotocol.io/v2/serving/express.md): createMcpHandler turns a server factory into a web-standard HTTP handler, and toNodeHandler adapts it once to Express's (req, res).
- [Hono](https://ts.sdk.modelcontextprotocol.io/v2/serving/hono.md): createMcpHandler turns a server factory into a web-standard HTTP handler, and handler.fetch takes the Request a Hono route already holds as c.req.raw — no Node adapter.
- [Fastify](https://ts.sdk.modelcontextprotocol.io/v2/serving/fastify.md): createMcpHandler turns a server factory into a web-standard HTTP handler, and toNodeHandler adapts it once to Node's (req, res) — a Fastify route hands it request.raw and reply.raw.
- [Web-standard runtimes](https://ts.sdk.modelcontextprotocol.io/v2/serving/web-standard.md): createMcpHandler returns a { fetch } object — the shape Cloudflare Workers, Deno, and Bun expect from a module's default export — so export default handler mounts it.
- [Sessions, state, scaling](https://ts.sdk.modelcontextprotocol.io/v2/serving/sessions-state-scaling.md): createMcpHandler builds a fresh server instance from your factory for every HTTP request and holds nothing between requests, so a v2 server is stateless and scales horizontally by default — Serve over HTTP is the…
- [Authorization](https://ts.sdk.modelcontextprotocol.io/v2/serving/authorization.md): Require a bearer token on a server you run: verification, protected-resource metadata, and per-tool scopes.
- [Legacy clients](https://ts.sdk.modelcontextprotocol.io/v2/serving/legacy-clients.md): A legacy client speaks a 2025-era protocol revision: it opens with initialize and sends no per-request _meta envelope.

## Clients

- [Connect](https://ts.sdk.modelcontextprotocol.io/v2/clients/connect.md): A client holds one connection to one server: construct a Client, pick a transport, and connect().
- [Calling](https://ts.sdk.modelcontextprotocol.io/v2/clients/calling.md): Every block on this page runs on a connected Client — Connect to a server shows the wiring — here paired in memory with an orders server that registers three tools, a resource, and a prompt.
- [Handle server requests](https://ts.sdk.modelcontextprotocol.io/v2/clients/server-requests.md): Declare each capability in the Client constructor's options — a server only sends your client a request it declared a capability for, and the SDK enforces that on both sides.
- [Roots (sunset)](https://ts.sdk.modelcontextprotocol.io/v2/clients/roots.md): A root is a file:// URI the client hands to the server as a boundary for its file operations.
- [Subscriptions](https://ts.sdk.modelcontextprotocol.io/v2/clients/subscriptions.md): A subscription stream is one long-lived subscriptions/listen request that carries every change notification you opted in to.
- [OAuth](https://ts.sdk.modelcontextprotocol.io/v2/clients/oauth.md): Sign an end user in from a client you build with the OAuth authorization-code flow.
- [Machine auth](https://ts.sdk.modelcontextprotocol.io/v2/clients/machine-auth.md): Authenticate a client with no user present: client credentials, private-key JWT, and cross-app access.
- [Middleware](https://ts.sdk.modelcontextprotocol.io/v2/clients/middleware.md): A middleware wraps the fetch a client transport uses, so it sees every HTTP request on the way out and every Response on the way back.
- [Caching](https://ts.sdk.modelcontextprotocol.io/v2/clients/caching.md): Caching is one feature with two halves: the server marks a result with a freshness hint, and the client's response cache serves it locally while it stays fresh.

## Protocol versions

- [Protocol versions](https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions.md): An era is a behavior family, not a version string.

## Advanced

- [Low-level server](https://ts.sdk.modelcontextprotocol.io/v2/advanced/low-level-server.md): Server is the protocol layer under McpServer: it routes each JSON-RPC request to the handler you register for that method string, and nothing more.
- [Custom methods](https://ts.sdk.modelcontextprotocol.io/v2/advanced/custom-methods.md): A custom method is a JSON-RPC method outside the MCP specification.
- [Schema libraries](https://ts.sdk.modelcontextprotocol.io/v2/advanced/schema-libraries.md): inputSchema accepts any Standard Schema that can produce JSON Schema — ArkType works as-is, no wrapper, exactly like the Zod schemas in Tools.
- [Custom transports](https://ts.sdk.modelcontextprotocol.io/v2/advanced/custom-transports.md): A transport moves JSONRPCMessage values in both directions over a channel the SDK knows nothing about.
- [Wire schemas](https://ts.sdk.modelcontextprotocol.io/v2/advanced/wire-schemas.md): @modelcontextprotocol/core exports the wire schemas — the exact Zod constants the SDK validates protocol and OAuth payloads against — for code that holds raw JSON instead of SDK objects.
- [Gateway](https://ts.sdk.modelcontextprotocol.io/v2/advanced/gateway.md): A gateway — a proxy, a worker pool, any process that fronts one MCP server with many short-lived clients — probes the server once and reuses the answer for every connection after it.

## Testing

- [Testing](https://ts.sdk.modelcontextprotocol.io/v2/testing.md): Drive your server through a real Client, in-process — no port, no socket, no mock transport.

## Troubleshooting

- [Troubleshooting](https://ts.sdk.modelcontextprotocol.io/v2/troubleshooting.md): Each heading on this page is the verbatim error message.

## Migration

- [Overview](https://ts.sdk.modelcontextprotocol.io/v2/migration/index.md): Pick the guide for your starting point.
- [Upgrade to v2](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2.md): Migrate MCP TypeScript SDK code from v1 (@modelcontextprotocol/sdk) to v2 (@modelcontextprotocol/core, /client, /server). Use when a user asks to migrate, upgrade, or port their MCP TypeScript code from v1 to v2.
- [2026-07-28 protocol support](https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md): This guide is for code already on the v2 packages that wants to speak the 2026-07-28 protocol revision — and for code written against an earlier v2 alpha that read wire-only members directly.

## Optional

- [llms-full.txt](https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt): every page above concatenated into one file
- [API reference](https://ts.sdk.modelcontextprotocol.io/v2/api/): generated per-package API reference
- [MCP specification](https://modelcontextprotocol.io/specification/latest)
- [v1 documentation](https://ts.sdk.modelcontextprotocol.io/)