MCP TypeScript SDK v2: split server and client packages on the 2026-07-28 spec

The problem MCP solves, and why a TypeScript SDK exists for it

MCP exists to separate the work of supplying context to an LLM from the work of talking to the LLM. The README states this directly: the protocol lets applications provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. Without a shared protocol, every host application that wants to expose a database, a file tree, or an internal API to a model ends up writing a bespoke integration. The SDK is the TypeScript implementation of that specification. It targets teams building the two ends of the connection: the server that exposes tools, resources and prompts, and the client that connects to servers, lists what they offer, and calls it. The README lists Node.js, Bun and Deno as supported runtimes, which matters because the transport layer differs between a stdio process and an HTTP handler. If you are writing a TypeScript service that needs to be callable by an MCP host, this repository is the reference implementation rather than one of several independent ports.

Two packages instead of one, and what the split changes

The v2 line publishes @modelcontextprotocol/server for building servers and @modelcontextprotocol/client for building clients. That is a change from the v1 packaging, and it has a practical consequence: a client-only application no longer pulls in server-side code, and a server does not carry client transports it will never instantiate. The README describes v2 as the stable release line, released alongside the 2026-07-28 spec, and states that v1.x continues to receive bug fixes and security updates for at least six months after v2's release. Two documentation sites exist in parallel: ts.sdk.modelcontextprotocol.io for v1 and the /v2/ path for the new line, which starts with a ten-minute server tutorial. That parallel structure is a signal about the intended audience. Teams already in production on v1 are not being pushed to migrate immediately. Teams starting fresh are pointed at v2.

Tool schemas come from Standard Schema, not from a bundled validator

The README states that tool and prompt schemas use Standard Schema, and that you can bring Zod v4, Valibot, ArkType, or any compatible library. The minimal example in the README imports zod/v4 and passes z.object({ name: z.string() }) as the inputSchema to server.registerTool. The handler then returns a content array with a single text entry. This is a deliberate decoupling: the SDK does not mandate a validator, so a codebase already standardized on Valibot does not need to add Zod as a second schema library. It also means the schema you pass must satisfy the Standard Schema interface, which is a constraint worth checking before assuming an arbitrary validation library will work. The registration call takes a name, an options object carrying description and inputSchema, and an async handler. There is no separate schema registration step.

Getting a stdio server running from the README example

Installation is a single package add. For npm it is npm install @modelcontextprotocol/server, with bun add @modelcontextprotocol/server and deno add npm:@modelcontextprotocol/server as the documented alternatives. The client follows the same pattern with @modelcontextprotocol/client. The README's minimal server imports McpServer from @modelcontextprotocol/server and StdioServerTransport from the subpath @modelcontextprotocol/server/stdio, constructs the server with a name and version, registers a greet tool, and then calls server.connect(transport) inside an async main function. That is the whole stdio path. For HTTP, the optional middleware packages are installed separately: @modelcontextprotocol/node wraps the Node.js Streamable HTTP transport for IncomingMessage and ServerResponse, while @modelcontextprotocol/express, @modelcontextprotocol/fastify and @modelcontextprotocol/hono provide framework helpers. The README is explicit that these adapters are intentionally thin and should not introduce new MCP functionality or business logic. Express and Fastify helpers are described as covering app defaults plus Host header validation; the Hono helper adds a JSON body parsing hook on top of that. Host header validation being called out by name suggests it is a security-relevant default rather than a convenience.

Where the SDK is the wrong tool, and what the README does not settle

The middleware packages are adapters only. If you need authentication flows, rate limiting, or request routing beyond what your framework already provides, that logic lives in your application, not in @modelcontextprotocol/express or its siblings. The README also does not describe how the Streamable HTTP transport behaves under partial failures, reconnects, or long-lived sessions; it points to the documentation site for serving over HTTP and stdio. Treat that as unverified here. The repository carries a NOASSERTION license identifier in the metadata, while the README's npm badge is labelled MIT licensed and the table of contents has a License section. Those two signals do not match, and the discrepancy is not resolved in the material available. If licence terms matter to your distribution model, read the LICENSE file in the repository and, where the stakes are high, get your own legal review rather than relying on the badge.

v1.x versus v2, and why the pull request limit is a signal

The README carries a warning that pull requests are limited to one per new contributor while v2 settles after the 2026-07-28 spec release, and that issues are the most useful feedback right now. It also asks for v2 feedback through a dedicated issue template. That is an unusual posture for a project that describes itself as the official SDK, and it tells you something concrete about the state of the code: the maintainers are prioritizing defect reports over external patches during the stabilization window. For a team evaluating adoption, this cuts both ways. You get a stable release line with a published spec target, and you get a slower path to landing your own fixes. If your integration depends on patching the SDK itself, budget for that delay or plan to fork. If you are consuming the published packages and filing issues, the constraint does not affect you.

A real alternative: writing a client against the raw specification

The obvious alternative is to implement the MCP wire format yourself against the specification at modelcontextprotocol.io/specification/latest, using your own JSON handling and transport code. The difference in approach is where the maintenance burden sits. With the SDK, the spec version you target is the version the package implements, and the README ties v2 to the 2026-07-28 spec explicitly. With a hand-rolled client, you control exactly which fields you send and receive, you avoid a dependency on a package line that is still receiving a high volume of feedback, and you can support a spec revision the SDK has not adopted yet. The cost is that every protocol change becomes your change. The SDK's split packages, Standard Schema integration, and middleware adapters exist precisely to absorb that work. For a one-off internal integration with a narrow tool surface, hand-rolling is defensible. For anything that will track the specification across revisions, the SDK is the cheaper position over time.

Upgrade cost and the migration path from v1

The README does not enumerate the breaking changes between v1 and v2. It points to a migration section on the v2 documentation site, and it maintains separate documentation for each line. That means the upgrade cost cannot be estimated from the repository front page alone. What is stated: v1.x gets bug fixes and security updates for at least six months after v2's release, v2 is the stable line, and the package names differ between the two. The package rename is the first thing to check in your dependency manifest, since @modelcontextprotocol/server and @modelcontextprotocol/client replace whatever the v1 layout used. The second is your schema library, because v2 tool definitions go through Standard Schema. The third is transport wiring, since the HTTP path now has separate middleware packages per framework. Read the migration guide before touching imports, and check the troubleshooting document for the errors it already covers.

Editorial conclusion

Adopt v2 if you are starting a new MCP server or client and can target the 2026-07-28 spec, since the stable line is now @modelcontextprotocol/server and @modelcontextprotocol/client. Stay on v1.x if you depend on the old package layout or cannot move to the new spec, noting the README's commitment of bug fixes and security updates for at least six months after v2's release. Before migrating, verify the published package names on npm, confirm which Standard Schema library your tool schemas use, and read the migration guide on the v2 documentation site rather than assuming the import paths carried over.

Official sources

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