GitHub

mcp_test

API reference for mcp_test.

An in-memory MCP client of a server, for tests (Effect's McpTest).

make_client builds the server with registrations, connects a client to it through JSON-RPC messages, as a transport would, and performs the handshake: initialize and notifications/initialized for a revision with sessions, the request _meta on every request for 2026-07-28::

client = yield from mcp_test.make_client(
    mcp_server.resource(uri="test://greeting", name="greeting", content=fx.succeed("hello")),
    protocols=(mcp_protocol.v2025_11_25,),
)
result = yield from client.read_resource({"uri": "test://greeting"})

Every message, both ways, is written as JSON text and read back, as the transports write and read it, and goes through the server's routing, middleware and response encoding, so results and errors are what a wire client gets (lists, not tuples). A request answered with an error fails with an McpError of its code, message and data. The server's notifications are queued on notifications in delivery order; its requests to the client (elicitation, sampling, roots) are answered with method not found. Client and server live in the surrounding Scope.

Re-exports

Values

AttributeTypeDescription
DEFAULT_CLIENT_INFOImplementation = {'name': 'McpTest', 'version': '1.0.0'}

Classes

Functions

make_client

make_client[RE = Never, RR = Never](registrations, *, protocols, protocol_version=None, name='McpTest', version='1.0.0', instructions=None, extensions=None, client_info=None, client_capabilities=None) -> Effect[McpTestClient, IllegalArgumentError | RE, RR | Scope]

A client of a server built with registrations (mcp_server.layer and the transports' registrations), speaking protocol_version, by default the first of protocols.

ParameterTypeDescription
registrationsLayer[Any, RE, RR | McpServer | McpServerClient]
protocolsSequence[AnyProtocolAdapter]
protocol_versionstr | None = None
namestr = 'McpTest'
versionstr = '1.0.0'
instructionsstr | None = None
extensionsMapping[str, Any] | None = None
client_infoImplementation | None = None
client_capabilitiesClientCapabilities | None = None

Returns Effect[McpTestClient, IllegalArgumentError | RE, RR | Scope]

def make_client[RE = Never, RR = Never](
    registrations: Layer[Any, RE, RR | McpServer | McpServerClient],
    *,
    protocols: Sequence[AnyProtocolAdapter],
    protocol_version: str | None = None,
    name: str = "McpTest",
    version: str = "1.0.0",
    instructions: str | None = None,
    extensions: Mapping[str, Any] | None = None,
    client_info: Implementation | None = None,
    client_capabilities: ClientCapabilities | None = None,
) -> Effect[McpTestClient, IllegalArgumentError | RE, RR | Scope]:
    """A client of a server built with ``registrations`` (``mcp_server.layer``
    and the transports' ``registrations``), speaking ``protocol_version``,
    by default the first of ``protocols``."""
    require_layer(registrations, "registrations")
    selected = (
        protocols[0]
        if protocol_version is None
        else next((p for p in protocols if p.protocol_version == protocol_version), None)
    )
    info: Implementation = or_default(client_info, DEFAULT_CLIENT_INFO)
    capabilities: ClientCapabilities = or_default(client_capabilities, {})

    @gen
    def run():
        if selected is None:
            return (
                yield from fail(
                    IllegalArgumentError(
                        f"MCP protocol {protocol_version} is not in the configured protocols"
                    )
                )
            )
        registry = yield from make_registry(protocols)
        # ``McpServerClient`` is provided per request, not to the build.
        registering: Layer[Any, Any, Any] = registrations
        built: Context[Any] = yield from registering.pipe(provide_merge(mcp_server.layer)).build()
        server = built.get_unsafe(McpServer)
        level = yield from CurrentLogLevel()
        queue = Queue[Notification, Never]()
        metadata: JsonObject | None = None
        if selected.is_stateless:
            metadata = {
                PROTOCOL_VERSION_META: selected.protocol_version,
                CLIENT_CAPABILITIES_META: cast("Any", capabilities),
                CLIENT_INFO_META: cast("Any", info),
            }
        client: McpTestClient

        def receive(frame: frames.Frame) -> Effect[None]:
            return client._receive(frame)  # pyright: ignore[reportPrivateUsage]

        connection = Connection(
            server,
            ServerInfo(
                name=name, version=version, instructions=instructions, extensions=extensions
            ),
            registry,
            server.next_client_id(),
            "stdio",
            broadcast=_from_server(receive),
            default_log_level=level,
        )
        wire = _Wire(connection)
        client = McpTestClient(selected.protocol_version, server, queue, wire, metadata)
        yield from acquire_release(
            sync(lambda: server.connect(connection)),
            lambda _, __: sync(lambda: server.disconnect(connection.client_id)).and_then(
                connection.close()
            ),
        )
        if not selected.is_stateless:
            yield from client.request(
                "initialize",
                {
                    "protocolVersion": selected.protocol_version,
                    "capabilities": cast("Any", capabilities),
                    "clientInfo": cast("Any", info),
                },
            ).or_die()
            yield from wire.send(notification("notifications/initialized", {}), receive)
        return client

    return cast("Any", run)