Repository navigation
Labels
v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixesIdeas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
Milestone
Description
This issue is to track changes we need to have
- Types - remove passthrough
- Class names - make it more like Python SDK (server, session etc)
- Clean up auth
- remove AS
- remove ProxyOAuthProvider (or make it more clear to not do token-passthrough)
- migrate to Zod4
- Fix: Barrel file exports #870
@KKonstantinov EDITs:
Please note the below is a wishlist, and will be introduced in v2 depending on demand and timeline considerations; Some of it would be opened up for contributors for a PR after the v2 refactor.
- Decouple from Zod, allow for any validator ("bring your own").
- Type-first as opposed to zod schema-first approach
- Protocol.ts - although the goal is to have symmetric client and server, protocol.ts contains nasty conditionals which can be executed only by client or server, but not both, defeating the purpose of an abstract class. File hard to read & extend.
- Tests - All tests under
/testdirectory - Tests - Reusable helpers under
/test/helperdirectory - e.g. creating mock server, mock client, connecting them together, etc. etc. (we already have a significant amount we could move there). - Decouple from
expressto allow for lighter SDK, and easier compatibility with other HTTP frameworks (e.g.Hono,fastify, others) - non-node environment considerations (e.g.
Bun,Denoon the backend,react-nativeon frontend, etc.) - Publish
@modelcontextprotocol/typescript-sdk-clientand@modelcontextprotocol/typescript-sdk-serverto reduce package size on users with a single consideration (e.g. either server or client) - clear abstracted way to define
experimentalfeatures in the SDK - DX quality of life improvements, such as inject your own logger
- DX - ability to listen on
onErrorand hook in custom behavior onMcpErrors thrown - Ability to pass in JSON schema on the higher-order abstraction (
McpServer) - DX - provide OpenTelemetry (@opentelemetry/api) capabilities out of the box - inject your own telemetry Tracer/Metrics Provider
- Examples - move out in another package or out of
src/- examples should import from @modelcontextprotocol/sdk to be readily copy-able as opposed to having relative imports in them - ctx object inside the tool extra for transport/server controls.
- Using
Headersas opposed to a custom object in request context
Reacted by Yurii, lin72h, Kent C. Dodds, Alex Nahas, williamsrosterfy, Gareth Andrew, Elias Djurfeldt, C. T. Lin, Jack Coy, Felix Weinberger and 2 more
Reacted by Frédéric Barthelet, lin72h, Yurii, Alex Nahas, Kent C. Dodds, Elias Djurfeldt, C. T. Lin, Jack Coy, Felix Weinberger, Alexandre Djerbetian and 2 more
Reacted by Scott
Metadata
Metadata
Assignees
Labels
v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixesIdeas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
Activity
jgoz commentedon Jul 29, 2025
It would be great to get Zod 4 (#555) in here too
nicolasembleton commentedon Aug 1, 2025
Does the team plan to migrate to Zod 4 @ihrpr ? (removing passThrough seems to be one step towards that)
KKonstantinov commentedon Aug 19, 2025
It would be great if we can include utilizing Typescript's features such as type generics, type inference more to make it a more typescript-native solution and reduce the amount of runtime-only checks.
E.g. PR #859 as a simple example, but there are so many more opportunities.
kentcdodds commentedon Aug 21, 2025
Is there any place we can find the current status of this work and get a sense for where help is needed and what breaking changes to expect? Preparing for breaking changes is important for my use case.
ochafik commentedon Oct 15, 2025
Something that would be nice for v2 is to use the Spec type definitions as they are, and tighten the diff between them and the zod schema-derived types (mostly, dropping passthrough might do the trick).
Took a stab at it in this wip branch (cc/ @felixweinberger )
KKonstantinov commentedon Nov 21, 2025
V2 idea dump (adding to above):
EDIT: Moving to main comment for readability.
chipgpt commentedon Nov 22, 2025
Possible to build it in a way so that Client and/or Server could run in a react-native app? Related issue: #1117
felixweinberger commentedon Dec 2, 2025
Going to keep this as a log of todos for v2:
cliffhall commentedon Dec 9, 2025
Renaming Server to Session
I mentioned this one to @ihrpr back when this issue was created, but it could use elaboration.
The class we call
Server(andMcpServer) in TS is calledSessionin the Python SDK. The Python naming is more on target. If you look at whatServeractually does, it manages a session for a single client (connected to it via a transport).We create an actual server with Express (or node:http or Hono or whatever) that listens on a port and handles traffic for multiple clients. In order to have an MCP Server that can handle multiple clients, what we have to do is create a new
ServerorMcpServerinstance and connect it to a concreteTransportimplementation.In our actual HTTP server, we map all of the transport/server pairs to their session ids, and when a message comes in, we use the associated transport to handle the message.
The thing that the transport is sending the message to is called a server, but it's really a session handler.
smolinari commentedon Dec 17, 2025
While Zod 4 support would be an improvement, I’d argue that decoupling Zod from the SDK altogether is the better long-term architectural choice. It won't stop you from using Zod 4, but would also allow others to use something else.
Currently, the tight coupling forces a specific validation library on all consumers, which creates several downstream issues:
Unnecessary bloat: It imposes a dependency on users who don't use Zod.
Version friction: It causes conflicts for anyone building tools around the SDK or integrating it into existing projects (e.g., vercel/ai#9387, rekog-labs/MCP-Nest#146, and even internal friction).
There has already been successful work done to decouple Zod in this fork: enthspace/mcp-sdk.
That implementation looks like a solid proof-of-concept for how we can keep the core lightweight. We should ideally leave schema validation to "devland," allowing users to plug in their preferred library (Zod, Valibot, ArkType, etc.) rather than baking one in.
Scott
cliffhall commentedon Dec 25, 2025
@KKonstantinov @felixweinberger is this really closed? A lot of boxes didn't get checked.
miniq15 commentedon Jan 2, 2026
Decouple from Zod, allow for any validator ("bring your own").,
When is it planned?