{"repo":"modelcontextprotocol/typescript-sdk","free":true,"listed":false,"github":"https://github.com/modelcontextprotocol/typescript-sdk","clone":"git clone https://github.com/modelcontextprotocol/typescript-sdk.git","description":"The official TypeScript SDK for Model Context Protocol servers and clients","language":"TypeScript","stars":13184,"topics":["mcp","mcp-client","mcp-server","typescript"],"license":null,"category":"llm_agent_framework","readme_excerpt":"# MCP TypeScript SDK\n\n\n> [!IMPORTANT]\n> **This is the `main` branch — v2 of the SDK** (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), implementing the [2026-07-28 MCP spec](https://modelcontextprotocol.io/specification/2026-07-28).\n>\n> **Have feedback? Please [open a v2 issue](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml)** — it is the most useful thing you can do for the SDK right now. The [v2 documentation](https://ts.sdk.modelcontextprotocol.io/v2/) starts with a ten-minute server tutorial.\n>\n> **v2 is the stable release line**, released alongside the 2026-07-28 spec. v1.x continues to receive bug fixes and security updates for at least 6 months after v2's release. v1 documentation: [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/) · v2: [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).\n\n\n> [!WARNING]\n> **We're limiting pull requests to 1 per new contributor while v2 settles after the [2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28) release.**\n>\n> [Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml) are the most useful feedback right now — we'll reopen PRs as v2 stabilizes.\n\n[](https://www.npmjs.com/package/@modelcontextprotocol/server)\n[](https://www.npmjs.com/package/@modelcontextprotocol/client) \n\n\nTable of Contents
\n\n- [Overview](#overview)\n- [Packages](#packages)\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n \n\n## Overview\n\nThe Model Context Protocol (MCP) allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.\n\nThis repository contains the TypeScript SDK implementation of the MCP specification. It runs on **Node.js**, **Bun**, and **Deno**, and ships:\n\n- MCP **server** libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)\n- MCP **client** libraries (transports, high-level helpers, OAuth helpers)\n- Optional **middleware packages** for specific runtimes/frameworks (Express, Fastify, Hono, Node.js HTTP)\n- Runnable **examples** (under [`examples/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples))\n\n## Packages\n\nThis monorepo publishes split packages:\n\n- **`@modelcontextprotocol/server`**: build MCP servers\n- **`@modelcontextprotocol/client`**: build MCP clients\n\nTool and prompt schemas use [Standard Schema](https://standardschema.dev/) — bring Zod v4, Valibot, ArkType, or any compatible library.\n\n### Middleware packages (optional)\n\nThe SDK also publishes small \"middleware\" packages under [`packages/middleware/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/packages/middleware) that help you **wire MCP into a specific runtime or web framework**.\n\nThey are intentionally thin adapters: they should not introduce new MCP functionality or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.\n\n- **`@modelcontextprotocol/node`**: Node.js Streamable HTTP transport wrapper for `IncomingMessage` / `ServerResponse`\n- **`@modelcontextprotocol/express`**: Express helpers (app defaults + Host header validation)\n- **`@modelcontextprotocol/fastify`**: Fastify helpers (app defaults + Host header validation)\n- **`@modelcontextprotocol/hono`**: Hono helpers (app defaults + JSON body parsing hook + Host header validation)\n\n## Installation\n\n### Server\n\n```bash\nnpm install @modelcontextprotocol/server\n# or\nbun add @modelcontextprotocol/server\n# or\ndeno add npm:@modelcontextprotocol/server\n```\n\n### Client\n\n```bash\nnpm install @modelcontextprotocol/client\n# or\nbun add @modelcontextprotocol/client\n# or\ndeno add npm:@modelcontextprotocol/client\n```\n\n### Optional middleware packages\n\nThe SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Fastify, Hono, or Node.js `http`).\n\nThese packages are intentionally thin adapters and should not introduce additional MCP features or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.\n\n```bash\n# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:\nnpm install @modelcontextprotocol/node\n\n# Express integration:\nnpm install @modelcontextprotocol/express express\n\n# Fastify integration:\nnpm install @modelcontextprotocol/fastify fastify\n\n# Hono integration:\nnpm install @modelcontextprotocol/hono hono\n```\n\n## Getting Started\n\nHere is what an MCP server looks like. This minimal example exposes a single `greet` tool over stdio:\n\n```typescript\nimport { McpServer } from '@modelcontextprotocol/server';\nimport { StdioServerTransport } from '@modelcontextprotocol/server/stdio';\nimport * as z from 'zod/v4';\n\nconst server = new McpServer({ name: 'greeting-server', version: '1.0.0' });\n\nserver.registerTool(\n 'greet',\n {\n description: 'Greet someone by name',\n inputSchema: z.object({ name: z.string() })\n },\n async ({ name }) => ({\n content: [{ type: 'text', text: `Hello, ${name}!` }]\n })\n);\n\nasync function main() {\n const transport = new StdioServerTransport();\n await server.connect(transport);\n}\n\nmain();\n```\n\nReady to build something real? Follow the step-by-step tutorials:\n\n- [Build your first server](docs/get-started/first-server.md) — a stdio weather-alert server, from `npm init` to a tool call\n- [Build your first client](docs/get-started/first-client.md) — connect to that server, list its tools, and call them\n\nFor runnable, end-to-end examples beyond the tutorials, see:\n\n- [`examples/README.md`](examples/README.md) — runnable, self-verifying client/server example pairs (one story per directory)\n\n## Documentation\n\n- [Build a server](docs/get-started/first-server.md) — your first MCP server, step by step\n- [Build a client](docs/get-started/first-client.md) — your first MCP client, step by step\n- [Documentation site](https://ts.sdk.modelcontextprotocol.io/v2/) — the full guides: tools, resources, prompts, serving over HTTP and stdio, clients, OAuth, and migration\n- [Troubleshooting](docs/troubleshooting.md) — common errors and their fixes\n- [API reference](https://ts.sdk.modelcontextprotocol.io/v2/api/)\n- [MCP documentation](https://modelcontextprotocol.io/docs)\n- [MCP specification](https://modelcontextprotocol.io/specification/latest)\n\n### Building docs locally\n\nTo work on the documentation site locally:\n\n```bash\npnpm docs:api # Generate the API reference markdown (output: docs/api/)\npnpm docs:dev # Start the VitePress dev server for the V2 site\npnpm docs:build # Build the V2 site (output: docs/.vitepress/dist/)\npnpm docs:multi # Build the combined V1 + V2 site (output: tmp/docs-combined/)\n```\n\nThe `docs:multi` script builds the V2 site from the current checkout, checks out the `v1.x` branch via a git worktree to build the V1 site, and produces a combined site with V1 docs at the root and V2 docs under `/v2/`.\n\n## v1 (legacy) documentation and fixes\n\nIf you are using the **v1** generation of the SDK, the **v1 API documentation** is available at [`https://ts.sdk.modelcontextprotocol.io/`](https://ts.sdk.modelcontextprotocol.io/). The v1 source code and any v1-specific fixes live on the long-lived\n[`v1.x` branch](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x). V2 API docs are at [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).\n\n## Contributing\n\nIssues and pull requests are welcome on GitHub at .\n\n## License\n\nThis project is licensed under the Apache License 2.0 for new contributions, with existing code under MIT. See the [LICENSE](LICENSE) file for details.\n","default_branch":"main","files":1115,"tree":[".changeset/README.md",".changeset/cancelled-request-id-zero.md",".changeset/config.json",".git-blame-ignore-revs",".github/CODEOWNERS",".github/ISSUE_TEMPLATE/v2-feedback.yml",".github/dependabot.yml",".github/workflows/claude.yml",".github/workflows/conformance.yml",".github/workflows/deploy-docs.yml",".github/workflows/examples.yml",".github/workflows/main.yml",".github/workflows/publish.yml",".github/workflows/release.yml",".github/workflows/update-spec-types.yml",".gitignore",".npmrc",".prettierignore",".prettierrc.json","CLAUDE.md","CODE_OF_CONDUCT.md","CONTRIBUTING.md","LICENSE","README.md","REVIEW.md","SECURITY.md","common/eslint-config/eslint.config.mjs","common/eslint-config/package.json","common/tsconfig/package.json","common/tsconfig/tsconfig.json","common/vitest-config/package.json","common/vitest-config/tsconfig.json","common/vitest-config/vitest.config.js","docs/.vitepress/config.mts","docs/.vitepress/llms.ts","docs/.vitepress/nav.ts","docs/.vitepress/theme/Banner.vue","docs/.vitepress/theme/MarkdownSource.vue","docs/.vitepress/theme/custom.css","docs/.vitepress/theme/index.ts","docs/_meta/CONVENTIONS.md","docs/advanced/custom-methods.md","docs/advanced/custom-transports.md","docs/advanced/gateway.md","docs/advanced/low-level-server.md","docs/advanced/schema-libraries.md","docs/advanced/wire-schemas.md","docs/behavior-surface-pins.md","docs/clients/caching.md","docs/clients/calling.md","docs/clients/connect.md","docs/clients/machine-auth.md","docs/clients/middleware.md","docs/clients/oauth.md","docs/clients/roots.md","docs/clients/server-requests.md","docs/clients/subscriptions.md","docs/get-started/examples.md","docs/get-started/first-client.md","docs/get-started/first-server.md","docs/get-started/packages.md","docs/get-started/real-host.md","docs/index.md","docs/migration/index.md","docs/migration/support-2026-07-28.md","docs/migration/upgrade-to-v2.md","docs/protocol-versions.md","docs/public/favicon.svg","docs/servers/completion.md","docs/servers/elicitation.md","docs/servers/errors.md","docs/servers/input-required.md","docs/servers/logging-progress-cancellation.md","docs/servers/notifications.md","docs/servers/prompts.md","docs/servers/resources.md","docs/servers/sampling.md","docs/servers/tools.md","docs/serving/authorization.md","docs/serving/express.md","docs/serving/fastify.md","docs/serving/hono.md","docs/serving/http.md","docs/serving/legacy-clients.md","docs/serving/sessions-state-scaling.md","docs/serving/stdio.md","docs/serving/web-standard.md","docs/testing.md","docs/troubleshooting.md","docs/v1/.vitepress/config.mts","docs/v1/.vitepress/theme/Banner.vue","docs/v1/.vitepress/theme/index.ts","examples/CONTRIBUTING.md","examples/README.md","examples/bearer-auth-web/README.md","examples/bearer-auth-web/client.ts","examples/bearer-auth-web/package.json","examples/bearer-auth-web/server.ts","examples/bearer-auth/README.md","examples/bearer-auth/client.ts","examples/bearer-auth/package.json","examples/bearer-auth/server.ts","examples/caching/README.md","examples/caching/client.ts","examples/caching/package.json","examples/caching/server.ts","examples/cli-client/.gitignore","examples/cli-client/README.md","examples/cli-client/cli.ts","examples/cli-client/client.ts","examples/cli-client/config.example.json","examples/cli-client/host/auth.ts","examples/cli-client/host/config.ts","examples/cli-client/host/content.ts","examples/cli-client/host/host.ts","examples/cli-client/host/loop.ts","examples/cli-client/host/naming.ts","examples/cli-client/host/ui.ts","examples/cli-client/package.json","examples/cli-client/providers/anthropic.ts","examples/cli-client/providers/gemini.ts","examples/cli-client/providers/openai.ts","examples/cli-client/providers/provider.ts","examples/cli-client/providers/scripted.ts","examples/cli-client/script/scriptedUi.ts","examples/cli-client/script/session.ts","examples/cli-client/server.ts","examples/cli-client/test/auth.test.ts","examples/cli-client/test/forms.test.ts","examples/cli-client/test/host.test.ts","examples/cli-client/test/providers.test.ts","examples/cli-client/vitest.config.js","examples/client-quickstart/.gitignore","examples/client-quickstart/README.md","examples/client-quickstart/package.json","examples/client-quickstart/src/index.ts","examples/client-quickstart/tsconfig.json","examples/custom-methods/README.md","examples/custom-methods/client.ts","examples/custom-methods/package.json","examples/custom-methods/server.ts","examples/custom-version/README.md","examples/custom-version/client.ts","examples/custom-version/package.json","examples/custom-version/server.ts","examples/dual-era/README.md","examples/dual-era/client.ts","examples/dual-era/package.json","examples/dual-era/server.ts","examples/elicitation/README.md","examples/elicitation/client.ts","examples/elicitation/package.json","examples/elicitation/server.ts","examples/eslint.config.mjs","examples/extension-capabilities/README.md","examples/extension-capabilities/client.ts","examples/extension-capabilities/package.json","examples/extension-capabilities/server.ts","examples/gateway/README.md","examples/gateway/client.ts","examples/gateway/package.json","examples/gateway/server.ts","examples/guides/README.md","examples/guides/advanced/custom-methods.examples.ts","examples/guides/advanced/custom-transports.examples.ts","examples/guides/advanced/gateway.examples.ts","examples/guides/advanced/low-level-server.examples.ts","examples/guides/advanced/schema-libraries.examples.ts","examples/guides/advanced/wire-schemas.examples.ts","examples/guides/clients/caching.examples.ts","examples/guides/clients/calling.examples.ts","examples/guides/clients/connect.examples.ts","examples/guides/clients/machine-auth.examples.ts","examples/guides/clients/middleware.examples.ts","examples/guides/clients/oauth.examples.ts","examples/guides/clients/roots.examples.ts","examples/guides/clients/server-requests.examples.ts","examples/guides/clients/subscriptions.examples.ts","examples/guides/get-started/firstClient.examples.ts","examples/guides/get-started/firstServer.examples.ts","examples/guides/get-started/packages.examples.ts","examples/guides/get-started/realHost.examples.ts","examples/guides/get-started/src/index.ts","examples/guides/index.examples.ts","examples/guides/protocolVersions.examples.ts","examples/guides/servers/completion.examples.ts","examples/guides/servers/elicitation.examples.ts","examples/guides/servers/errors.examples.ts","examples/guides/servers/input-required.examples.ts","examples/guides/servers/logging-progress-cancellation.examples.ts","examples/guides/servers/notifications.examples.ts","examples/guides/servers/prompts.examples.ts","examples/guides/servers/resources.examples.ts","examples/guides/servers/sampling.examples.ts","examples/guides/servers/tools.examples.ts","examples/guides/serving/authorization.examples.ts","examples/guides/serving/authorization.web.examples.ts","examples/guides/serving/express.examples.ts","examples/guides/serving/fastify.examples.ts","examples/guides/serving/hono.examples.ts","examples/guides/serving/http.examples.ts","examples/guides/serving/legacy-clients.examples.ts","examples/guides/serving/sessions-state-scaling.examples.ts","examples/guides/serving/stdio.examples.ts","examples/guides/serving/webStandard.examples.ts","examples/guides/testing.examples.ts","examples/guides/troubleshooting.examples.ts","examples/guides/troubleshooting.stdio.examples.ts","examples/hono/README.md","examples/hono/client.ts","examples/hono/package.json","examples/hono/server.ts","examples/json-response/README.md","examples/json-response/client.ts","examples/json-response/package.json","examples/json-response/server.ts","examples/legacy-routing/README.md","examples/legacy-routing/client.ts","examples/legacy-routing/package.json","examples/legacy-routing/server.ts","examples/mrtr/README.md","examples/mrtr/client.ts","examples/mrtr/package.json","examples/mrtr/server.ts","examples/oauth-client-credentials/README.md","examples/oauth-client-credentials/client.ts","examples/oauth-client-credentials/package.json","examples/oauth-client-credentials/server.ts","examples/oauth/README.md","examples/oauth/client.ts","examples/oauth/dualModeAuth.ts","examples/oauth/package.json","examples/oauth/server.ts","examples/oauth/simpleOAuthClient.ts","examples/oauth/simpleOAuthClientProvider.ts","examples/oauth/simpleTokenProvider.ts","examples/package.json","examples/parallel-calls/README.md","examples/parallel-calls/client.ts","examples/parallel-calls/package.json","examples/parallel-calls/server.ts","examples/prompts/README.md","examples/prompts/client.ts","examples/prompts/package.json","examples/prompts/server.ts","examples/repl/README.md","examples/repl/client.ts","examples/repl/package.json","examples/repl/server.ts","examples/resources/README.md","examples/resources/client.ts","examples/resources/package.json","examples/resources/server.ts","examples/sampling/README.md","examples/sampling/client.ts","examples/sampling/package.json","examples/sampling/server.ts","examples/schema-validators/README.md","examples/schema-validators/client.ts","examples/schema-validators/package.json","examples/schema-validators/server.ts","examples/scoped-tools/README.md","examples/scoped-tools/client.ts","examples/scoped-tools/package.json","examples/scoped-tools/server.ts","examples/server-quickstart/.gitignore","examples/server-quickstart/README.md","examples/server-quickstart/package.json","examples/server-quickstart/src/index.ts","examples/server-quickstart/tsconfig.json","examples/shared/eslint.config.mjs","examples/shared/package.json","examples/shared/src/args.ts","examples/shared/src/auth.ts","examples/shared/src/authServer.ts","examples/shared/src/clientCredentialsAuthServer.ts","examples/shared/src/inMemoryEventStore.ts","examples/shared/src/index.ts","examples/shared/src/indexAuth.ts","examples/shared/test/demoInMemoryOAuthProvider.test.ts","examples/shared/tsconfig.json","examples/shared/vitest.config.js","examples/sse-polling/README.md","examples/sse-polling/client.ts","examples/sse-polling/package.json","examples/sse-polling/server.ts","examples/standalone-get/README.md","examples/standalone-get/client.ts","examples/standalone-get/package.json","examples/standalone-get/server.ts","examples/stateless-legacy/README.md","examples/stateless-legacy/client.ts","examples/stateless-legacy/package.json","examples/stateless-legacy/server.ts","examples/stickynotes/README.md","examples/stickynotes/client.ts","examples/stickynotes/package.json","examples/stickynotes/server.ts","examples/streaming/README.md","examples/streaming/client.ts","examples/streaming/package.json","examples/streaming/server.ts","examples/subscriptions/README.md","examples/subscriptions/client.ts","examples/subscriptions/package.json","examples/subscriptions/server.ts","examples/todos-server/README.md","examples/todos-server/package.json","examples/todos-server/server.ts","examples/todos-server/todos.ts","examples/tools/README.md","examples/tools/client.ts","examples/tools/package.json","examples/tools/server.ts","examples/tsconfig.json","lefthook-local.example.yml","lefthook.yml","package.json","packages/client/CHANGELOG.md","packages/client/README.md","packages/client/eslint.config.mjs","packages/client/package.json","packages/client/src/client/auth.examples.ts","packages/client/src/client/auth.ts","packages/client/src/client/authErrors.ts","packages/client/src/client/authExtensions.examples.ts","packages/client/src/client/authExtensions.ts","packages/client/src/client/authSeam.ts","packages/client/src/client/client.examples.ts","packages/client/src/client/client.ts","packages/client/src/client/crossAppAccess.ts","packages/client/src/client/middleware.examples.ts","packages/client/src/client/middleware.ts","packages/client/src/client/probeClassifier.ts","packages/client/src/client/responseCache.ts","packages/client/src/client/sse.ts","packages/client/src/client/stdio.ts","packages/client/src/client/streamableHttp.examples.ts","packages/client/src/client/streamableHttp.ts","packages/client/src/client/versionNegotiation.ts","packages/client/src/fromJsonSchema.ts","packages/client/src/index.ts","packages/client/src/shimsBrowser.ts","packages/client/src/shimsNode.ts","packages/client/src/shimsWorkerd.ts","packages/client/src/stdio.ts","packages/client/src/validators/ajv.ts","packages/client/src/validators/cfWorker.ts","packages/client/test/client/auth.test.ts","packages/client/test/client/authExtensions.test.ts","packages/client/test/client/barrelClean.test.ts","packages/client/test/client/bodyDerivedProbeHeaders.test.ts","packages/client/test/client/clientTypeSurface.test.ts","packages/client/test/client/connectPrior.test.ts","packages/client/test/client/coreBoundary.test.ts","packages/client/test/client/crossAppAccess.test.ts","packages/client/test/client/crossSpawn.test.ts","packages/client/test/client/discover.test.ts","packages/client/test/client/envelopeAutoEmission.test.ts","packages/client/test/client/errorBrandConformance.test.ts","packages/client/test/client/inputRequiredEngine.test.ts","packages/client/test/client/jsonSchemaValidatorOverride.test.ts","packages/client/test/client/legacyHandshakeModernOnlyGuard.test.ts","packages/client/test/client/listen.test.ts","packages/client/test/client/mcpParamMirroring.test.ts","packages/client/test/client/middleware.test.ts","packages/client/test/client/modernEraInboundDrop.test.ts","packages/client/test/client/probeAuthSeam.test.ts","packages/client/test/client/probeClassifier.test.ts","packages/client/test/client/probeFixtureCorpus.test.ts","packages/client/test/client/protocolExport.test.ts","packages/client/test/client/responseCache.test.ts","packages/client/test/client/responseCacheCodec.test.ts","packages/client/test/client/sse.test.ts","packages/client/test/client/sseErrorBrand.test.ts","packages/client/test/client/stdio.test.ts","packages/client/test/client/stdioEnvPins.test.ts","packages/client/test/client/streamableHttp.test.ts","packages/client/test/client/tokenProvider.test.ts","packages/client/test/client/versionNegotiation.test.ts","packages/client/test/client/workerdSchemaPreload.test.ts","packages/client/test/helpers/ensureBuilt.ts","packages/client/tsconfig.json","packages/client/tsdown.config.ts","packages/client/typedoc.json","packages/client/vitest.config.js","packages/client/vitest.setup.js","packages/codemod/CHANGELOG.md","packages/codemod/README.md","packages/codemod/batch-test/.gitignore","packages/codemod/batch-test/README.md","packages/codemod/batch-test/analyze-prompt.md","packages/codemod/batch-test/repos.json","packages/codemod/eslint.config.mjs","packages/codemod/package.json","packages/codemod/src/bin/batchTest.ts","packages/codemod/src/cli.ts","packages/codemod/src/index.ts","packages/codemod/src/migrations/index.ts","packages/codemod/src/migrations/v1-to-v2/index.ts"],"storefront":"/r/modelcontextprotocol","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/modelcontextprotocol/typescript-sdk/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}