MCP TypeScript SDK: Building Model Context Protocol Servers and Clients

What the MCP TypeScript SDK Provides

Model Context Protocol defines a standard way for applications to provide context to large language models, separating context provision from LLM interaction. The TypeScript SDK is the official implementation of that protocol. It ships as split packages: `@modelcontextprotocol/server` for building the side that exposes tools, resources, and prompts, and `@modelcontextprotocol/client` for building the side that connects to those servers.

The README describes the SDK as running on Node.js, Bun, and Deno. The current v2 release implements the 2026-07-28 MCP specification. The v1.x line continues to receive bug fixes and security updates for at least six months after v2's release, giving teams time to migrate. The SDK is maintained by Model Context Protocol, a Series of LF Projects, LLC, as stated in package.json, and last pushed on 2026-09-27.

Package Structure: Server, Client, and Middleware Layers

The monorepo publishes distinct npm packages for each concern. The core packages are `@modelcontextprotocol/server` and `@modelcontextprotocol/client`. These handle MCP protocol logic, stdio transport, Streamable HTTP transport, and OAuth helpers.

Optional middleware packages sit under `packages/middleware/` and serve as thin adapters for specific runtimes. They add no MCP functionality of their own:

- `@modelcontextprotocol/node`: Node.js Streamable HTTP transport wrapper for IncomingMessage and ServerResponse - `@modelcontextprotocol/express`: Express helpers including app defaults and Host header validation - `@modelcontextprotocol/fastify`: Fastify helpers including app defaults and Host header validation - `@modelcontextprotocol/hono`: Hono helpers including app defaults, a JSON body parsing hook, and Host header validation

Tool and prompt schemas use Standard Schema, which allows the caller to bring Zod v4, Valibot, ArkType, or any compatible validation library. This avoids locking the SDK to a single schema library while preserving static type safety.

Installing @modelcontextprotocol/server and @modelcontextprotocol/client

Server-side install via npm, bun, or deno:

npm install @modelcontextprotocol/server
# or
bun add @modelcontextprotocol/server
# or
deno add npm:@modelcontextprotocol/server

Client-side install follows the same pattern:

npm install @modelcontextprotocol/client
# or
bun add @modelcontextprotocol/client
# or
deno add npm:@modelcontextprotocol/client

Framework middleware packages are installed separately. For example, to wire MCP into an Express application:

npm install @modelcontextprotocol/express express

The package.json engines field sets the minimum Node.js version to 20. The package manager used in development is pnpm 10.26.1. Teams on Node.js 18 or earlier cannot use this SDK.

Building a Minimal MCP Server with Stdio Transport

The README gives a minimal server example that registers a single tool over stdio. The pattern is: create a server, register tools with a schema and handler, then connect a transport:

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `Hello, ${name}!` }]
    })
);

The `inputSchema` field accepts any Standard Schema-compatible object, so the `z.object(...)` call above can be replaced with equivalent Valibot or ArkType schemas. The handler receives the validated input and returns a content array. For Streamable HTTP transport instead of stdio, the middleware packages handle the transport wiring without changes to the tool registration code.

Runnable end-to-end example pairs are in the `examples/` directory. The README lists named examples covering OAuth, elicitation, parallel calls, custom methods, caching, and gateway patterns.

V2 Versus V1: The 2026-07-28 Specification Gap

The main branch holds v2, which implements the 2026-07-28 MCP specification. V1.x implemented an earlier spec version. The README notes that v2 is the stable release line as of the 2026-07-28 spec release, and that v1.x will continue to receive bug fixes and security updates for at least six months after that date.

The most visible change for existing server authors is the schema API. V1 used a different schema interface; v2 requires Standard Schema-compatible libraries. The README explicitly asks for v2 feedback through a separate issue template and warns that pull requests are limited to one per new contributor while the codebase settles after the spec release.

The monorepo also publishes a `@modelcontextprotocol/server-legacy` package (version 2.1.0 as of the 2026-09-23 release), which likely serves teams still integrating against v1 behavior. The README does not document its exact scope, so teams considering it should read the package's own documentation before depending on it.

Where the MCP TypeScript SDK Is the Wrong Tool

The SDK is designed for building protocol-level MCP servers and clients, not for higher-level application logic. Teams building AI-powered applications that consume MCP servers need a client integration, but if their application already has one through a host like Claude Desktop, they do not need to implement their own MCP client.

The Node.js 20 floor is a hard dependency. Serverless environments or edge runtimes that do not support Node.js 20, Bun, or Deno cannot run this SDK. The engine field in package.json makes this explicit.

The split-package architecture means that mixing v1 and v2 packages in the same project is a source of subtle bugs. Teams migrating an existing server built on an older SDK version should treat the migration as a full replacement rather than an incremental update, given the schema interface change.

The Python MCP SDK from the same organization is the correct alternative for teams working in Python. It implements the same protocol, so a Python server built on it is interoperable with TypeScript clients built on this SDK, as both conform to the MCP specification.

Docs, Examples, and the Contribution Constraint

The full documentation site is at ts.sdk.modelcontextprotocol.io/v2/ and covers tools, resources, prompts, HTTP and stdio serving, OAuth, and client building. The `docs/` directory in the repository contains the source for that site. Locally, the docs server and API reference can be built with:

pnpm docs:api
pnpm docs:dev

The `examples/` directory holds runnable client-server pairs organized by story, including examples for OAuth, elicitation, parallel calls, and a gateway pattern. A contributing guide at `examples/CONTRIBUTING.md` describes how the example structure works.

The README notes a pull-request constraint: while v2 settles, new contributors are limited to one pull request each. The project asks that feedback be submitted as issues using the v2 feedback template rather than pull requests. This is a temporary policy during the post-release stabilization period, not a permanent limitation.

Editorial conclusion

Teams building MCP servers or clients in TypeScript, JavaScript, or a compatible runtime should use this SDK. Developers on Python or another language will find the matching language-specific SDK from the Model Context Protocol organization a better fit. Before adopting v2, confirm that any existing v1.x-based tooling has been audited against the 2026-07-28 spec changes, since the Standard Schema tool interface replaced the previous schema API. The minimum runtime is Node.js 20, and that hard floor will block adoption on older server environments.

Frequently asked questions

Official sources

1. Issues
2. modelcontextprotocol/typescript-sdk on GitHub
3. Project website
4. README
5. Releases