Version Packages (alpha)

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and publish to npm yourself or setup this action to publish automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

⚠️⚠️⚠️⚠️⚠️⚠️

main is currently in pre mode so this branch has prereleases rather than normal releases. If you want to exit prereleases, run changeset pre exit on main.

⚠️⚠️⚠️⚠️⚠️⚠️

Releases

@modelcontextprotocol/client@2.0.0-alpha.3

Minor Changes

• #2049 4f226c1 Thanks @KKonstantinov! - Add SdkHttpError subclass
  with typed .status / .statusText accessors for HTTP transport failures. StreamableHTTPClientTransport now throws SdkHttpError (which extends SdkError) for non-OK HTTP responses; SSEClientTransport throws SdkHttpError for 401-after-reauth (circuit breaker).

• #1974 db83829 Thanks @felixweinberger! - Add custom (non-spec)
  method support: a 3-arg setRequestHandler(method, schemas, handler) / setNotificationHandler(method, schemas, handler) form for vendor-prefixed methods, and a request(req, resultSchema) overload (also on ctx.mcpReq.send) for typed custom-method results. Spec-method
  calls are unchanged.

  Response result-schema validation failure now rejects with SdkError(InvalidResult) instead of a raw ZodError. Adds SdkErrorCode.InvalidResult.

• #1653 6bec24a Thanks @rechedev9! - Add validateClientMetadataUrl()
  utility for early validation of clientMetadataUrl

  Exports a validateClientMetadataUrl() function that OAuthClientProvider implementations can call in their constructors to fail fast on invalid URL-based client IDs, instead of discovering the error deep in the auth flow.

• #1887 96db044 Thanks @felixweinberger! - Export isSpecType and
  specTypeSchemas records for runtime validation of any MCP spec type by name. isSpecType.ContentBlock(value) is a type predicate; specTypeSchemas.ContentBlock is a StandardSchemaV1Sync<ContentBlock> validator — validate() returns the result synchronously. Guards are
  standalone functions, so arr.filter(isSpecType.ContentBlock) works. Also export the SpecTypeName, SpecTypes, and StandardSchemaV1Sync types.

• #1871 9fc9070 Thanks @felixweinberger! - Move stdio transports
  to a ./stdio subpath export. Import StdioClientTransport, getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, and StdioServerParameters from @modelcontextprotocol/client/stdio, and StdioServerTransport from @modelcontextprotocol/server/stdio. The
  @modelcontextprotocol/client root entry no longer pulls in node:child_process, node:stream, or cross-spawn, fixing bundling for browser and Cloudflare Workers targets; the @modelcontextprotocol/server root entry drops its node:stream reference. Node.js, Bun, and
  Deno consumers update the import path; runtime behavior is unchanged.

Patch Changes

• #1897 434b2f1 Thanks @felixweinberger! - Stop bundling
  @cfworker/json-schema into the main package barrel. Previously CfWorkerJsonSchemaValidator was re-exported from the core internal barrel, so tsdown inlined the @cfworker/json-schema dependency into every consumer's bundle even when it was never used. The named validator
  classes are now reachable only via the explicit @modelcontextprotocol/{client,server}/validators/{ajv,cf-worker} subpaths and the runtime _shims conditional, so consumers that import only from the root entry point no longer ship the validator dep.

• #1834 42cb6b2 Thanks @felixweinberger! - Export
  InMemoryTransport for in-process testing.

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• #1655 1eb3123 Thanks @nielskaspers! - fix(client): append custom
  Accept headers to spec-required defaults in StreamableHTTPClientTransport

  Custom Accept headers provided via requestInit.headers are now appended to the spec-mandated Accept types instead of being overwritten. This ensures the required media types (application/json, text/event-stream for POST; text/event-stream for GET SSE) are always present
  while allowing users to include additional types for proxy/gateway routing.

• #2088 16d13ab Thanks @mattzcarey! - Bundle automatic JSON Schema
  validator defaults in @modelcontextprotocol/client and @modelcontextprotocol/server runtime shims.

  Client and server pick the right validator automatically based on the runtime: the Node shim uses AJV, the browser/workerd shim uses @cfworker/json-schema. Both backends are bundled into the shim chunks that select them, so the default code path needs no extra installs —
  import { McpServer } from '@modelcontextprotocol/server' does not pull ajv or @cfworker/json-schema into the root entry chunk.

  The named validator classes remain part of the public surface for consumers who want to customize the built-in backend (pre-register schemas by $id, register custom AJV formats, switch dialects, change @cfworker/json-schema draft). They are exposed through explicit
  subpaths so they do not bloat the root index chunk:

  • import { AjvJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/ajv'

  • import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/cf-worker'

    Importing from one of these subpaths means the corresponding peer dep (ajv + ajv-formats, or @cfworker/json-schema) must be in your package.json. The shim keeps its own vendored copy for the default path, so a project can use the subpath in some files and rely on the
    default in others.

    The jsonSchemaValidator interface remains the public extension point for replacing validation entirely with a custom implementation.

• #1976 55b1f06 Thanks @felixweinberger! - refactor: subclasses
  override _wrapHandler hook instead of redeclaring setRequestHandler.

• #1895 b256546 Thanks @felixweinberger! - Fix runtime crash on
  tools/list when a tool's inputSchema comes from zod 4.0–4.1. The SDK requires ~standard.jsonSchema (StandardJSONSchemaV1, added in zod 4.2.0); previously a missing jsonSchema crashed at undefined[io]. standardSchemaToJsonSchema now detects zod 4 schemas lacking
  jsonSchema and falls back to the SDK-bundled z.toJSONSchema(), emitting a one-time console warning. zod 3 schemas (which the bundled zod 4 converter cannot introspect) and non-zod schema libraries without jsonSchema get a clear error pointing to fromJsonSchema(). The
  workspace zod catalog is also bumped to ^4.2.0.

@modelcontextprotocol/express@2.0.0-alpha.3

Minor Changes

• #1907 7cccc2a Thanks @felixweinberger! - Add OAuth
  Resource-Server glue to the Express adapter: requireBearerAuth middleware (token verification + RFC 6750 WWW-Authenticate challenges), mcpAuthMetadataRouter (serves RFC 9728 Protected Resource Metadata and mirrors RFC 8414 AS metadata at the resource origin), the
  getOAuthProtectedResourceMetadataUrl helper, and the OAuthTokenVerifier interface. These restore the v1 src/server/auth Resource-Server pieces as first-class v2 API so MCP servers can plug into an external Authorization Server with a few lines of Express wiring.

Patch Changes

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• Updated dependencies [434b2f1, db83829,
  42cb6b2, df4b6cc,
  2c0c481, 2a7611d,
  e15a8ef, 96db044,
  9fc9070, 16d13ab,
  55b1f06, b256546]:

  • @modelcontextprotocol/server@2.0.0-alpha.3

@modelcontextprotocol/server@2.0.0-alpha.3

Minor Changes

• #1974 db83829 Thanks @felixweinberger! - Add custom (non-spec)
  method support: a 3-arg setRequestHandler(method, schemas, handler) / setNotificationHandler(method, schemas, handler) form for vendor-prefixed methods, and a request(req, resultSchema) overload (also on ctx.mcpReq.send) for typed custom-method results. Spec-method
  calls are unchanged.

  Response result-schema validation failure now rejects with SdkError(InvalidResult) instead of a raw ZodError. Adds SdkErrorCode.InvalidResult.

• #1887 96db044 Thanks @felixweinberger! - Export isSpecType and
  specTypeSchemas records for runtime validation of any MCP spec type by name. isSpecType.ContentBlock(value) is a type predicate; specTypeSchemas.ContentBlock is a StandardSchemaV1Sync<ContentBlock> validator — validate() returns the result synchronously. Guards are
  standalone functions, so arr.filter(isSpecType.ContentBlock) works. Also export the SpecTypeName, SpecTypes, and StandardSchemaV1Sync types.

• #1871 9fc9070 Thanks @felixweinberger! - Move stdio transports
  to a ./stdio subpath export. Import StdioClientTransport, getDefaultEnvironment, DEFAULT_INHERITED_ENV_VARS, and StdioServerParameters from @modelcontextprotocol/client/stdio, and StdioServerTransport from @modelcontextprotocol/server/stdio. The
  @modelcontextprotocol/client root entry no longer pulls in node:child_process, node:stream, or cross-spawn, fixing bundling for browser and Cloudflare Workers targets; the @modelcontextprotocol/server root entry drops its node:stream reference. Node.js, Bun, and
  Deno consumers update the import path; runtime behavior is unchanged.

Patch Changes

• #1897 434b2f1 Thanks @felixweinberger! - Stop bundling
  @cfworker/json-schema into the main package barrel. Previously CfWorkerJsonSchemaValidator was re-exported from the core internal barrel, so tsdown inlined the @cfworker/json-schema dependency into every consumer's bundle even when it was never used. The named validator
  classes are now reachable only via the explicit @modelcontextprotocol/{client,server}/validators/{ajv,cf-worker} subpaths and the runtime _shims conditional, so consumers that import only from the root entry point no longer ship the validator dep.

• #1834 42cb6b2 Thanks @felixweinberger! - Export
  InMemoryTransport for in-process testing.

• #1788 df4b6cc Thanks @claygeo! - Prevent stack overflow in
  StreamableHTTPServerTransport.close() with re-entrant guard

• #1855 2c0c481 Thanks @Christian-Sidak! - Add | undefined to
  optional callback and function properties on WebStandardStreamableHTTPServerTransportOptions (sessionIdGenerator, onsessioninitialized, onsessionclosed) and corresponding private fields.

  This fixes TS2430 errors for consumers using exactOptionalPropertyTypes: true without skipLibCheck, where optional properties with function types need explicit | undefined to match their emitted declarations.

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• #1901 e15a8ef Thanks @felixweinberger! -
  registerTool/registerPrompt accept a raw Zod shape ({ field: z.string() }) for inputSchema/outputSchema/argsSchema in addition to a wrapped Standard Schema. Raw shapes are auto-wrapped with z.object(). The raw-shape overloads are @deprecated; prefer wrapping
  with z.object().

  Also widens the completable() constraint from StandardSchemaWithJSON to StandardSchemaV1 so v1's completable(z.string(), fn) continues to work.

• #2088 16d13ab Thanks @mattzcarey! - Bundle automatic JSON Schema
  validator defaults in @modelcontextprotocol/client and @modelcontextprotocol/server runtime shims.

  Client and server pick the right validator automatically based on the runtime: the Node shim uses AJV, the browser/workerd shim uses @cfworker/json-schema. Both backends are bundled into the shim chunks that select them, so the default code path needs no extra installs —
  import { McpServer } from '@modelcontextprotocol/server' does not pull ajv or @cfworker/json-schema into the root entry chunk.

  The named validator classes remain part of the public surface for consumers who want to customize the built-in backend (pre-register schemas by $id, register custom AJV formats, switch dialects, change @cfworker/json-schema draft). They are exposed through explicit
  subpaths so they do not bloat the root index chunk:

  • import { AjvJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/ajv'

  • import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/cf-worker'

    Importing from one of these subpaths means the corresponding peer dep (ajv + ajv-formats, or @cfworker/json-schema) must be in your package.json. The shim keeps its own vendored copy for the default path, so a project can use the subpath in some files and rely on the
    default in others.

    The jsonSchemaValidator interface remains the public extension point for replacing validation entirely with a custom implementation.

• #1976 55b1f06 Thanks @felixweinberger! - refactor: subclasses
  override _wrapHandler hook instead of redeclaring setRequestHandler.

• #1895 b256546 Thanks @felixweinberger! - Fix runtime crash on
  tools/list when a tool's inputSchema comes from zod 4.0–4.1. The SDK requires ~standard.jsonSchema (StandardJSONSchemaV1, added in zod 4.2.0); previously a missing jsonSchema crashed at undefined[io]. standardSchemaToJsonSchema now detects zod 4 schemas lacking
  jsonSchema and falls back to the SDK-bundled z.toJSONSchema(), emitting a one-time console warning. zod 3 schemas (which the bundled zod 4 converter cannot introspect) and non-zod schema libraries without jsonSchema get a clear error pointing to fromJsonSchema(). The
  workspace zod catalog is also bumped to ^4.2.0.

@modelcontextprotocol/fastify@2.0.0-alpha.3

Patch Changes

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• Updated dependencies [434b2f1, db83829,
  42cb6b2, df4b6cc,
  2c0c481, 2a7611d,
  e15a8ef, 96db044,
  9fc9070, 16d13ab,
  55b1f06, b256546]:

  • @modelcontextprotocol/server@2.0.0-alpha.3

@modelcontextprotocol/hono@2.0.0-alpha.3

Patch Changes

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• Updated dependencies [434b2f1, db83829,
  42cb6b2, df4b6cc,
  2c0c481, 2a7611d,
  e15a8ef, 96db044,
  9fc9070, 16d13ab,
  55b1f06, b256546]:

  • @modelcontextprotocol/server@2.0.0-alpha.3

@modelcontextprotocol/node@2.0.0-alpha.3

Patch Changes

• #1896 5433f40 Thanks @felixweinberger! - Mark hono peer
  dependency as optional. @modelcontextprotocol/node only uses getRequestListener from @hono/node-server (Node HTTP ↔ Web Standard conversion), which does not require the hono framework at runtime. Consumers no longer need to install hono to use
  NodeStreamableHTTPServerTransport. Note: @hono/node-server itself still declares hono as a hard peer, so package managers may emit a warning; this is upstream and harmless for getRequestListener-only usage.

• #1898 2a7611d Thanks @felixweinberger! - Add top-level types
  field (and typesVersions on client/server for their subpath exports) so consumers on legacy moduleResolution: "node" can resolve type declarations. The exports map remains the source of truth for nodenext/bundler resolution. The typesVersions map includes entries
  for subpaths added by sibling PRs in this series (zod-schemas, stdio); those entries are no-ops until the corresponding dist/*.d.mts files exist.

• Updated dependencies [434b2f1, db83829,
  42cb6b2, df4b6cc,
  2c0c481, 2a7611d,
  e15a8ef, 96db044,
  9fc9070, 16d13ab,
  55b1f06, b256546]:

  • @modelcontextprotocol/server@2.0.0-alpha.3

@modelcontextprotocol/core@2.0.0-alpha.2

Minor Changes

• #2049 4f226c1 Thanks @KKonstantinov! - Add SdkHttpError subclass
  with typed .status / .statusText accessors for HTTP transport failures. StreamableHTTPClientTransport now throws SdkHttpError (which extends SdkError) for non-OK HTTP responses; SSEClientTransport throws SdkHttpError for 401-after-reauth (circuit breaker).

• #1974 db83829 Thanks @felixweinberger! - Add custom (non-spec)
  method support: a 3-arg setRequestHandler(method, schemas, handler) / setNotificationHandler(method, schemas, handler) form for vendor-prefixed methods, and a request(req, resultSchema) overload (also on ctx.mcpReq.send) for typed custom-method results. Spec-method
  calls are unchanged.

  Response result-schema validation failure now rejects with SdkError(InvalidResult) instead of a raw ZodError. Adds SdkErrorCode.InvalidResult.

• #2088 16d13ab Thanks @mattzcarey! - Bundle automatic JSON Schema
  validator defaults in @modelcontextprotocol/client and @modelcontextprotocol/server runtime shims.

  Client and server pick the right validator automatically based on the runtime: the Node shim uses AJV, the browser/workerd shim uses @cfworker/json-schema. Both backends are bundled into the shim chunks that select them, so the default code path needs no extra installs —
  import { McpServer } from '@modelcontextprotocol/server' does not pull ajv or @cfworker/json-schema into the root entry chunk.

  The named validator classes remain part of the public surface for consumers who want to customize the built-in backend (pre-register schemas by $id, register custom AJV formats, switch dialects, change @cfworker/json-schema draft). They are exposed through explicit
  subpaths so they do not bloat the root index chunk:

  • import { AjvJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/ajv'

  • import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/{client,server}/validators/cf-worker'

    Importing from one of these subpaths means the corresponding peer dep (ajv + ajv-formats, or @cfworker/json-schema) must be in your package.json. The shim keeps its own vendored copy for the default path, so a project can use the subpath in some files and rely on the
    default in others.

    The jsonSchemaValidator interface remains the public extension point for replacing validation entirely with a custom implementation.

Patch Changes

• #1930 bdfd7f0 Thanks @Christian-Sidak! - Fix requestStream to
  call tasks/result for failed tasks instead of yielding a hardcoded ProtocolError. When a task reaches the failed terminal status, the stream now retrieves and yields the actual stored result (matching the behavior for completed tasks), as required by the spec.

• #1901 e15a8ef Thanks @felixweinberger! -
  registerTool/registerPrompt accept a raw Zod shape ({ field: z.string() }) for inputSchema/outputSchema/argsSchema in addition to a wrapped Standard Schema. Raw shapes are auto-wrapped with z.object(). The raw-shape overloads are @deprecated; prefer wrapping
  with z.object().

  Also widens the completable() constraint from StandardSchemaWithJSON to StandardSchemaV1 so v1's completable(z.string(), fn) continues to work.

• #1976 55b1f06 Thanks @felixweinberger! - refactor: subclasses
  override _wrapHandler hook instead of redeclaring setRequestHandler.

• #1768 866c08d Thanks @felixweinberger! - Allow additional JSON
  Schema properties in elicitInput's requestedSchema type by adding .catchall(z.unknown()), matching the pattern used by inputSchema. This fixes type incompatibility when using Zod v4's .toJSONSchema() output which includes extra properties like $schema and additionalProperties.

• #1895 b256546 Thanks @felixweinberger! - Fix runtime crash on
  tools/list when a tool's inputSchema comes from zod 4.0–4.1. The SDK requires ~standard.jsonSchema (StandardJSONSchemaV1, added in zod 4.2.0); previously a missing jsonSchema crashed at undefined[io]. standardSchemaToJsonSchema now detects zod 4 schemas lacking
  jsonSchema and falls back to the SDK-bundled z.toJSONSchema(), emitting a one-time console warning. zod 3 schemas (which the bundled zod 4 converter cannot introspect) and non-zod schema libraries without jsonSchema get a clear error pointing to fromJsonSchema(). The
  workspace zod catalog is also bumped to ^4.2.0.

@modelcontextprotocol/test-e2e@2.0.0-alpha.1

Patch Changes

• #2203 4a5c863 Thanks @felixweinberger! - Add consumer-sourced
  e2e requirements (behaviors real SDK dependents rely on) and run the interaction matrix over the legacy HTTP+SSE transport, with known failures recording where v2 intentionally differs.

• #2179 1998a18 Thanks @felixweinberger! - Add the end-to-end
  behavior test suite as a workspace package: a requirements manifest covering protocol-visible SDK behavior across the in-memory, stdio, and Streamable HTTP transports, ported from the v1.x branch and extended with coverage for v2 features.