GitHub

mcp_protocol

API reference for mcp_protocol.

The MCP protocol revisions a server or client speaks (Effect's McpProtocol).

Each revision is a ProtocolAdapter: its version, whether it keeps a session from initialize ("stateful") or carries the client's identity in every request's _meta ("stateless", 2026-07-28), its JSON-RPC batch and HTTP header policy, and the fields its schema knows. A server takes a non-empty tuple of them; the first is the one offered when a client asks for a version the server does not speak::

mcp_server.layer_stdio(
    name="notes", version="1.0.0",
    protocols=(mcp_protocol.v2025_11_25, mcp_protocol.v2025_06_18),
)

make_registry checks such a tuple (not empty, no version twice) and Registry.select picks the adapter for an offered version.

Re-exports

Values

AttributeTypeDescription
v2024_11_05ProtocolAdapter[Literal['2024-11-05']]

MCP 2024-11-05. Over HTTP it is served on the single-endpoint Streamable HTTP transport, not the historical two-endpoint HTTP+SSE one.

v2025_03_26ProtocolAdapter[Literal['2025-03-26']]

MCP 2025-03-26, the revision that accepts JSON-RPC batches.

v2025_06_18ProtocolAdapter[Literal['2025-06-18']]

MCP 2025-06-18.

v2025_11_25ProtocolAdapter[Literal['2025-11-25']]

MCP 2025-11-25.

v2026_07_28ProtocolAdapter[Literal['2026-07-28']]

MCP 2026-07-28: no initialize and no sessions; each request's _meta carries the protocol version, client info and capabilities, and server/discover describes the server.

Types

TypeDefinitionDescription
ProtocolVersiontype ProtocolVersion = Literal['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25', '2026-07-28']
StatefulProtocolVersiontype StatefulProtocolVersion = Literal['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25']
Runtimetype Runtime = Literal['stateful', 'stateless']
AnyProtocolAdaptertype AnyProtocolAdapter = ProtocolAdapter[Any]

Classes

Functions

make_registry

make_registry(protocols) -> Effect[Registry, IllegalArgumentError]

The registry of protocols: fails when there are none or two declare the same version. Later changes to protocols are not seen.

ParameterTypeDescription
protocolsSequence[AnyProtocolAdapter]

Returns Effect[Registry, IllegalArgumentError]

def make_registry(
    protocols: Sequence[AnyProtocolAdapter],
) -> Effect[Registry, IllegalArgumentError]:
    """The registry of ``protocols``: fails when there are none or two
    declare the same version. Later changes to ``protocols`` are not seen."""
    copied = tuple(protocols)
    if not copied:
        return fail(IllegalArgumentError("McpServer requires at least one MCP protocol"))
    seen: set[str] = set()
    for protocol in copied:
        if protocol.protocol_version in seen:
            return fail(
                IllegalArgumentError(f"Duplicate MCP protocol version: {protocol.protocol_version}")
            )
        seen.add(protocol.protocol_version)
    return succeed(Registry(copied))

reverse_error

reverse_error(operation) -> Callable[[object], ReverseError]

The error of a failed request to the client: an unsupported operation (any value tagged McpReverseOperationUnsupported, so one from another copy of the class too) stays itself, anything else is wrapped in an McpReverseOperationError of operation.

ParameterTypeDescription
operationReverseOperation

Returns Callable[[object], ReverseError]

def reverse_error(operation: ReverseOperation) -> Callable[[object], ReverseError]:
    """The error of a failed request to the client: an unsupported
    operation (any value tagged ``McpReverseOperationUnsupported``, so one
    from another copy of the class too) stays itself, anything else is
    wrapped in an ``McpReverseOperationError`` of ``operation``."""

    def of(cause: object) -> ReverseError:
        if getattr(cause, "_tag", None) == McpReverseOperationUnsupported._tag:  # pyright: ignore[reportPrivateUsage]
            return cast("McpReverseOperationUnsupported", cause)
        return McpReverseOperationError(operation, cause)

    return of