McpProtocol unstable

Defines the MCP protocol implementations that an McpServer can support.

18 exports Since v4.0.0 Source

Models

AnyProtocolAdapter

interface unstable

Since v4.0.0

The operational shape shared by protocol adapters.

Signature

interface AnyProtocolAdapter<out Version extends string = string, HandlerRequirements = unknown, out Runtime extends RuntimeDescriptor = RuntimeDescriptor> {
  readonly clientNotificationRpcs: ErasedRpcGroup;
  readonly clientRpcs: ErasedClientRpcGroup;
  readonly installHandlers: (core: any, lifecycle: any, target: any) => Effect<void, never, HandlerRequirements>;
  readonly makeReverseClient: (profile: any) => Effect<McpReverseClient, never, Scope | Protocol>;
  readonly normalizeCancellation: (payload: unknown) => Effect<any, unknown>;
  readonly payloadCodecs: (rpc: AnyWithProps) => PayloadCodecs;
  readonly projectNotification: (notification: any) => Effect<ProjectedNotification | undefined, any>;
  readonly protocolVersion: Version;
  readonly runtime: Runtime;
  readonly serverNotificationRpcs: ErasedRpcGroup<AnyWithProps>;
  readonly serverRequestRpcs: Any;
}

ErasedClientRpcGroup

interface unstable

Since v4.0.0

The additional operation required from the complete client RPC group.

Signature

interface ErasedClientRpcGroup extends ErasedRpcGroup {
  readonly prefix: (prefix: string) => RpcGroup<any>;
}

ErasedRpcGroup

interface unstable

Since v4.0.0

The operations required from an RPC group after its RPC union is erased.

Signature

interface ErasedRpcGroup<RpcType extends Rpc.Any = Rpc.Any> {
  readonly requests: ReadonlyMap<string, RpcType>;
}

PayloadCodecs

interface unstable

Since v4.0.0

Payload codecs used by a protocol adapter.

Signature

interface PayloadCodecs {
  readonly decode: (input: unknown) => Effect<unknown, SchemaError>;
  readonly encode: (input: unknown) => Effect<unknown, SchemaError>;
}

ProjectedNotification

interface unstable

Since v4.0.0

A notification projected into a protocol-specific payload.

Signature

interface ProjectedNotification {
  readonly payload: unknown;
  readonly tag: string;
}

ProtocolAdapter

interface unstable

Since v4.0.0

An MCP protocol adapter that can be supplied to McpServer.

Signature

interface ProtocolAdapter<out Version extends ProtocolVersion = ProtocolVersion, out Runtime extends RuntimeDescriptor = RuntimeDescriptor> extends AnyProtocolAdapter<Version, unknown, Runtime> {}

ProtocolVersion

type unstable

Since v4.0.0

The MCP protocol versions implemented by this release.

Signature

type ProtocolVersion = "2024-11-05" | "2025-03-26" | "2025-06-18" | "2025-11-25" | "2026-07-28"

RuntimeDescriptor

type unstable

Since v4.0.0

Lifecycle runtime declaration carried by a protocol adapter.

Signature

type RuntimeDescriptor = StatefulRuntimeDescriptor | StatelessRuntimeDescriptor

StatefulProtocolVersion

type unstable

Since v4.0.0

MCP protocol versions that use initialization and server-managed sessions.

Signature

type StatefulProtocolVersion = Exclude<ProtocolVersion, "2026-07-28">

StatefulRuntimeDescriptor

interface unstable

Since v4.0.0

Stateful lifecycle runtime declaration carried by a protocol adapter.

Signature

interface StatefulRuntimeDescriptor {
  readonly _tag: "Stateful";
  readonly transport: TransportPolicy;
}

StatelessRuntimeDescriptor

interface unstable

Since v4.0.0

Stateless lifecycle runtime declaration carried by a protocol adapter.

Signature

interface StatelessRuntimeDescriptor {
  readonly _tag: "Stateless";
  readonly profileFromRequestMetadata: (metadata: unknown) => Effect<StatelessRuntimeProfile, unknown>;
  readonly transport: TransportPolicy;
}

StatelessRuntimeProfile

interface unstable

Since v4.0.0

Request information decoded by a stateless MCP runtime.

Signature

interface StatelessRuntimeProfile {
  readonly clientCapabilities: JsonObject;
  readonly clientInfo?: Implementation;
  readonly protocolVersion: string;
  readonly requestMetadata: JsonObject;
}

TransportPolicy

interface unstable

Since v4.0.0

Transport behavior declared by an MCP runtime descriptor.

Signature

interface TransportPolicy {
  readonly http: {
    readonly requiresVersionHeader?: boolean;
  };
  readonly jsonRpc: {
    readonly acceptsBatches: boolean;
  };
}

Protocols

v2024_11_05

unstable

Since v4.0.0

The MCP 2024-11-05 protocol implementation.

Details

It provides the dated schema and stdio behavior. When supplied to McpServer.layerHttp, the server uses its single-endpoint Streamable HTTP compatibility transport; it does not implement the historical two-endpoint HTTP+SSE transport.

Signature

declare const v2024_11_05: ProtocolAdapter<"2024-11-05", StatefulRuntimeDescriptor>

v2025_03_26

unstable

Since v4.0.0

The MCP 2025-03-26 protocol implementation.

Signature

declare const v2025_03_26: ProtocolAdapter<"2025-03-26", StatefulRuntimeDescriptor>

v2025_06_18

unstable

Since v4.0.0

The MCP 2025-06-18 protocol implementation.

Signature

declare const v2025_06_18: ProtocolAdapter<"2025-06-18", StatefulRuntimeDescriptor>

v2025_11_25

unstable

Since v4.0.0

The MCP 2025-11-25 protocol implementation.

Signature

declare const v2025_11_25: ProtocolAdapter<"2025-11-25", StatefulRuntimeDescriptor>

v2026_07_28

unstable

Since v4.0.0

The MCP 2026-07-28 protocol implementation.

Details

This revision uses request-scoped metadata instead of initialization and protocol-level sessions.

When the selected transport supports server notifications, discovery advertises change-notification capabilities and subscriptions/listen delivers the requested notifications over the long-lived response.

Signature

declare const v2026_07_28: ProtocolAdapter<"2026-07-28", StatelessRuntimeDescriptor>