v2: limit public exports

CLAUDE.md

@@ -62,6 +62,19 @@ The SDK is organized into three main layers:
     - `Server` (`packages/server/src/server/server.ts`) - Server implementation extending Protocol with request handler registration
     - `McpServer` (`packages/server/src/server/mcp.ts`) - High-level server API with simplified resource/tool/prompt registration
 
+### Public API Exports
+
+The SDK has a two-layer export structure to separate internal code from the public API:
+
+- **`@modelcontextprotocol/core`** (main entry, `packages/core/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
+- **`@modelcontextprotocol/core/public`** (`packages/core/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
+- **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core/public`.
+
+When modifying exports:
+- Use explicit named exports, not `export *`, in package `index.ts` files and `core/public`.
+- Adding a symbol to a package `index.ts` makes it public API — do so intentionally.
+- Internal helpers should stay in the core internal barrel and not be added to `core/public` or package index files.
+
 ### Transport System
 
 Transports (`packages/core/src/shared/transport.ts`) provide the communication layer:

examples/client-quickstart/tsconfig.json

@@ -15,6 +15,9 @@
             "@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
+            ],
+            "@modelcontextprotocol/core/public": [
+                "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
             ]
         }
     },

examples/client/tsconfig.json

@@ -10,6 +10,9 @@
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/index.ts"
             ],
+            "@modelcontextprotocol/core/public": [
+                "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
+            ],
             "@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
             "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"],
             "@modelcontextprotocol/examples-shared": ["./node_modules/@modelcontextprotocol/examples-shared/src/index.ts"]

examples/server-quickstart/tsconfig.json

@@ -14,6 +14,9 @@
             "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
+            ],
+            "@modelcontextprotocol/core/public": [
+                "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
             ]
         }
     },

examples/server/tsconfig.json

@@ -13,6 +13,9 @@
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
             ],
+            "@modelcontextprotocol/core/public": [
+                "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
+            ],
             "@modelcontextprotocol/examples-shared": ["./node_modules/@modelcontextprotocol/examples-shared/src/index.ts"],
             "@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
             "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"]

examples/shared/tsconfig.json

@@ -12,6 +12,9 @@
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"
             ],
+            "@modelcontextprotocol/core/public": [
+                "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"
+            ],
             "@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"],
             "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"],
             "@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"],

packages/client/src/client/sse.ts

@@ -26,7 +26,7 @@ export type SSEClientTransportOptions = {
      * When an `authProvider` is specified and the SSE connection is started:
      * 1. The connection is attempted with any existing access token from the `authProvider`.
      * 2. If the access token has expired, the `authProvider` is used to refresh the token.
-     * 3. If token refresh fails or no access token exists, and auth is required, {@linkcode OAuthClientProvider.redirectToAuthorization} is called, and an {@linkcode UnauthorizedError} will be thrown from {@linkcode index.Protocol.connect | connect}/{@linkcode SSEClientTransport.start | start}.
+     * 3. If token refresh fails or no access token exists, and auth is required, {@linkcode OAuthClientProvider.redirectToAuthorization} is called, and an {@linkcode UnauthorizedError} will be thrown from {@linkcode client/client.Client.connect | connect}/{@linkcode SSEClientTransport.start | start}.
      *
      * After the user has finished authorizing via their user agent, and is redirected back to the MCP client application, call {@linkcode SSEClientTransport.finishAuth} with the authorization code before retrying the connection.
      *

packages/client/src/client/streamableHttp.ts

@@ -88,7 +88,7 @@ export type StreamableHTTPClientTransportOptions = {
      * When an `authProvider` is specified and the connection is started:
      * 1. The connection is attempted with any existing access token from the `authProvider`.
      * 2. If the access token has expired, the `authProvider` is used to refresh the token.
-     * 3. If token refresh fails or no access token exists, and auth is required, {@linkcode OAuthClientProvider.redirectToAuthorization} is called, and an {@linkcode UnauthorizedError} will be thrown from {@linkcode index.Protocol.connect | connect}/{@linkcode StreamableHTTPClientTransport.start | start}.
+     * 3. If token refresh fails or no access token exists, and auth is required, {@linkcode OAuthClientProvider.redirectToAuthorization} is called, and an {@linkcode UnauthorizedError} will be thrown from {@linkcode client/client.Client.connect | connect}/{@linkcode StreamableHTTPClientTransport.start | start}.
      *
      * After the user has finished authorizing via their user agent, and is redirected back to the MCP client application, call {@linkcode StreamableHTTPClientTransport.finishAuth} with the authorization code before retrying the connection.
      *

packages/client/src/index.ts

@@ -1,14 +1,66 @@
-export * from './client/auth.js';
-export * from './client/authExtensions.js';
-export * from './client/client.js';
-export * from './client/middleware.js';
-export * from './client/sse.js';
-export * from './client/stdio.js';
-export * from './client/streamableHttp.js';
-export * from './client/websocket.js';
+// Public API for @modelcontextprotocol/client.
+//
+// This file defines the complete public surface. It consists of:
+//   - Package-specific exports: listed explicitly below (named imports)
+//   - Protocol-level types: re-exported from @modelcontextprotocol/core/public
+//
+// Any new export added here becomes public API. Use named exports, not wildcards.
+
+export type {
+    AddClientAuthentication,
+    AuthResult,
+    ClientAuthMethod,
+    OAuthClientProvider,
+    OAuthDiscoveryState,
+    OAuthServerInfo
+} from './client/auth.js';
+export {
+    auth,
+    buildDiscoveryUrls,
+    discoverAuthorizationServerMetadata,
+    discoverOAuthMetadata,
+    discoverOAuthProtectedResourceMetadata,
+    discoverOAuthServerInfo,
+    exchangeAuthorization,
+    extractResourceMetadataUrl,
+    extractWWWAuthenticateParams,
+    fetchToken,
+    isHttpsUrl,
+    parseErrorResponse,
+    prepareAuthorizationCodeRequest,
+    refreshAuthorization,
+    registerClient,
+    selectClientAuthMethod,
+    selectResourceURL,
+    startAuthorization,
+    UnauthorizedError
+} from './client/auth.js';
+export type {
+    ClientCredentialsProviderOptions,
+    PrivateKeyJwtProviderOptions,
+    StaticPrivateKeyJwtProviderOptions
+} from './client/authExtensions.js';
+export {
+    ClientCredentialsProvider,
+    createPrivateKeyJwtAuth,
+    PrivateKeyJwtProvider,
+    StaticPrivateKeyJwtProvider
+} from './client/authExtensions.js';
+export type { ClientOptions } from './client/client.js';
+export { Client } from './client/client.js';
+export { getSupportedElicitationModes } from './client/client.js';
+export type { LoggingOptions, Middleware, RequestLogger } from './client/middleware.js';
+export { applyMiddlewares, createMiddleware, withLogging, withOAuth } from './client/middleware.js';
+export type { SSEClientTransportOptions } from './client/sse.js';
+export { SSEClientTransport, SseError } from './client/sse.js';
+export type { StdioServerParameters } from './client/stdio.js';
+export { DEFAULT_INHERITED_ENV_VARS, getDefaultEnvironment, StdioClientTransport } from './client/stdio.js';
+export type { StartSSEOptions, StreamableHTTPClientTransportOptions, StreamableHTTPReconnectionOptions } from './client/streamableHttp.js';
+export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
+export { WebSocketClientTransport } from './client/websocket.js';
 
 // experimental exports
-export * from './experimental/index.js';
+export { ExperimentalClientTasks } from './experimental/tasks/client.js';
 
-// re-export shared types
-export * from '@modelcontextprotocol/core';
+// re-export curated public API from core
+export * from '@modelcontextprotocol/core/public';

packages/client/tsconfig.json

@@ -6,6 +6,7 @@
         "paths": {
             "*": ["./*"],
             "@modelcontextprotocol/core": ["./node_modules/@modelcontextprotocol/core/src/index.ts"],
+            "@modelcontextprotocol/core/public": ["./node_modules/@modelcontextprotocol/core/src/exports/public/index.ts"],
             "@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"],
             "@modelcontextprotocol/client/_shims": ["./src/shimsNode.ts"]
         }

packages/core/package.json

@@ -20,6 +20,20 @@
         "mcp",
         "core"
     ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs"
+        },
+        "./types": {
+            "types": "./src/exports/types/index.ts",
+            "import": "./src/exports/types/index.ts"
+        },
+        "./public": {
+            "types": "./src/exports/public/index.ts",
+            "import": "./src/exports/public/index.ts"
+        }
+    },
     "scripts": {
         "typecheck": "tsgo -p tsconfig.json --noEmit",
         "lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",

packages/core/src/experimental/tasks/interfaces.ts

@@ -14,7 +14,7 @@ import type {
     Result,
     Task,
     ToolExecution
-} from '../../types/types.js';
+} from '../../types/index.js';
 
 // ============================================================================
 // Task Handler Types (for registerToolTask)

packages/core/src/experimental/tasks/stores/inMemory.ts

@@ -3,7 +3,7 @@
  * @experimental
  */
 
-import type { Request, RequestId, Result, Task } from '../../../types/types.js';
+import type { Request, RequestId, Result, Task } from '../../../types/index.js';
 import type { CreateTaskOptions, QueuedMessage, TaskMessageQueue, TaskStore } from '../interfaces.js';
 import { isTerminal } from '../interfaces.js';
 

packages/core/src/exports/public/index.ts

@@ -0,0 +1,136 @@
+/**
+ * Curated public API exports for @modelcontextprotocol/core.
+ *
+ * This module defines the stable, public-facing API surface. Client and server
+ * packages re-export from here so that end users only see supported symbols.
+ *
+ * Internal utilities (Protocol class, stdio parsing, schema helpers, etc.)
+ * remain available via the internal barrel (@modelcontextprotocol/core) for
+ * use by client/server packages.
+ */
+
+// Auth error classes
+export * from '../../auth/errors.js';
+
+// SDK error types (local errors that never cross the wire)
+export { SdkError, SdkErrorCode } from '../../errors/sdkErrors.js';
+
+// Auth TypeScript types (NOT Zod schemas like OAuthMetadataSchema)
+export type {
+    AuthorizationServerMetadata,
+    OAuthClientInformation,
+    OAuthClientInformationFull,
+    OAuthClientInformationMixed,
+    OAuthClientMetadata,
+    OAuthClientRegistrationError,
+    OAuthErrorResponse,
+    OAuthMetadata,
+    OAuthProtectedResourceMetadata,
+    OAuthTokenRevocationRequest,
+    OAuthTokens,
+    OpenIdProviderDiscoveryMetadata,
+    OpenIdProviderMetadata
+} from '../../shared/auth.js';
+
+// Auth utilities
+export { checkResourceAllowed, resourceUrlFromServerUrl } from '../../shared/authUtils.js';
+
+// Metadata utilities
+export { getDisplayName } from '../../shared/metadataUtils.js';
+
+// Protocol types (NOT the Protocol class itself or mergeCapabilities)
+export type {
+    BaseContext,
+    ClientContext,
+    NotificationOptions,
+    ProgressCallback,
+    ProtocolOptions,
+    RequestOptions,
+    RequestTaskStore,
+    ServerContext,
+    TaskContext,
+    TaskRequestOptions
+} from '../../shared/protocol.js';
+export { DEFAULT_REQUEST_TIMEOUT_MSEC } from '../../shared/protocol.js';
+
+// Response message types
+export type {
+    BaseResponseMessage,
+    ErrorMessage,
+    ResponseMessage,
+    ResultMessage,
+    TaskCreatedMessage,
+    TaskStatusMessage
+} from '../../shared/responseMessage.js';
+export { takeResult, toArrayAsync } from '../../shared/responseMessage.js';
+
+// Transport types (NOT normalizeHeaders)
+export type { FetchLike, Transport, TransportSendOptions } from '../../shared/transport.js';
+export { createFetchWithInit } from '../../shared/transport.js';
+
+// URI Template
+export type { Variables } from '../../shared/uriTemplate.js';
+export { UriTemplate } from '../../shared/uriTemplate.js';
+
+// Types — all TypeScript types (standalone interfaces + schema-derived).
+// This is the one intentional `export *`: types.ts contains only spec-derived TS
+// types, and every type there should be public. See comment in types.ts.
+export * from '../../types/types.js';
+
+// Constants
+export {
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    JSONRPC_VERSION,
+    LATEST_PROTOCOL_VERSION,
+    METHOD_NOT_FOUND,
+    PARSE_ERROR,
+    RELATED_TASK_META_KEY,
+    SUPPORTED_PROTOCOL_VERSIONS
+} from '../../types/constants.js';
+
+// Enums
+export { ProtocolErrorCode } from '../../types/enums.js';
+
+// Error classes
+export { ProtocolError, UrlElicitationRequiredError } from '../../types/errors.js';
+
+// Type guards
+export {
+    assertCompleteRequestPrompt,
+    assertCompleteRequestResourceTemplate,
+    isInitializedNotification,
+    isInitializeRequest,
+    isJSONRPCErrorResponse,
+    isJSONRPCNotification,
+    isJSONRPCRequest,
+    isJSONRPCResultResponse,
+    isTaskAugmentedRequestParams
+} from '../../types/guards.js';
+
+// Experimental task types and classes
+export { assertClientRequestTaskCapability, assertToolsCallTaskCapability } from '../../experimental/tasks/helpers.js';
+export type {
+    BaseQueuedMessage,
+    CreateTaskOptions,
+    CreateTaskServerContext,
+    QueuedError,
+    QueuedMessage,
+    QueuedNotification,
+    QueuedRequest,
+    QueuedResponse,
+    TaskMessageQueue,
+    TaskServerContext,
+    TaskStore,
+    TaskToolExecution
+} from '../../experimental/tasks/interfaces.js';
+export { isTerminal } from '../../experimental/tasks/interfaces.js';
+export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
+
+// Validator types and classes
+export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
+export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
+export { CfWorkerJsonSchemaValidator } from '../../validators/cfWorkerProvider.js';
+export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from '../../validators/types.js';

packages/core/src/exports/types/index.ts

@@ -1 +1 @@
-export type * from '../../types/types.js';
+export type * from '../../types/index.js';

packages/core/src/index.ts

@@ -9,7 +9,7 @@ export * from './shared/stdio.js';
 export * from './shared/toolNameValidation.js';
 export * from './shared/transport.js';
 export * from './shared/uriTemplate.js';
-export * from './types/types.js';
+export * from './types/index.js';
 export * from './util/inMemory.js';
 export * from './util/schema.js';
 

packages/core/src/shared/metadataUtils.ts

@@ -1,4 +1,4 @@
-import type { BaseMetadata } from '../types/types.js';
+import type { BaseMetadata } from '../types/index.js';
 
 /**
  * Utilities for working with {@linkcode BaseMetadata} objects.

packages/core/src/shared/protocol.ts

@@ -39,7 +39,7 @@ import type {
     Task,
     TaskCreationParams,
     TaskStatusNotification
-} from '../types/types.js';
+} from '../types/index.js';
 import {
     CancelTaskResultSchema,
     CreateTaskResultSchema,
@@ -58,7 +58,7 @@ import {
     RELATED_TASK_META_KEY,
     SUPPORTED_PROTOCOL_VERSIONS,
     TaskStatusNotificationSchema
-} from '../types/types.js';
+} from '../types/index.js';
 import type { AnyObjectSchema, AnySchema, SchemaOutput } from '../util/schema.js';
 import { parseSchema } from '../util/schema.js';
 import type { ResponseMessage } from './responseMessage.js';
@@ -687,7 +687,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
     /**
      * Attaches to the given transport, starts it, and starts listening for messages.
      *
-     * The {@linkcode Protocol} object assumes ownership of the {@linkcode Transport}, replacing any callbacks that have already been set, and expects that it is the only user of the {@linkcode Transport} instance going forward.
+     * The caller assumes ownership of the {@linkcode Transport}, replacing any callbacks that have already been set, and expects that it is the only user of the {@linkcode Transport} instance going forward.
      */
     async connect(transport: Transport): Promise<void> {
         this._transport = transport;