Get Started

Building an MCP Client: Discovery, Routing, and Dual-Era Fallback

A modern MCP client repeats its contract on every request. Its hardest compatibility decision is knowing when an old server is truly old and when a modern server is reporting a correctable error.

85 minutesBuildPythonFree lesson

Learning Objectives

  • Build every MCP 2026-07-28 request with current metadata.
  • Probe stdio servers with server/discover and select a mutually supported version.
  • Authorize a bounded legacy probe only for explicitly allowlisted peers.
  • Accept a legacy era only after validating a positive initialize result for a supported revision.
  • Merge deterministic tool lists without silently overwriting collisions.
  • Route calls to the peer that owns each tool without inventing protocol sessions.

The Problem

An agent host usually talks to more than one MCP server. It must discover each server, merge tool catalogs, resolve duplicate names, route calls, and recover from transport failure.

The 2026-07-28 revision makes the steady state simpler because each request is self-contained. Compatibility makes startup more subtle. A client may encounter:

  • a modern server that supports the preferred version;
  • a modern server that returns a recognized version or header error;
  • a legacy server that has never heard of server/discover;
  • a legacy server that stays silent until it receives initialize.

Treating every probe error as legacy is dangerous. A malformed modern request, an overloaded server, a dead process, and an old server can all produce the same timeout or connection close. Those signals are ambiguous. The client must combine explicit operator intent with positive protocol evidence before it chooses the legacy era.

The Concept

A peer, not a protocol session

Keep one transport peer record for each server process or endpoint:

  • transport handle or send function;
  • selected protocol era and version;
  • last discovered server capabilities;
  • last deterministic tool list;
  • pending request ids for correlation;
  • transport health.

This is client bookkeeping. It is not protocol session state. On modern MCP, the server still receives current version and capabilities on every request.

Build every modern request from scratch

Python
def modern_request(request_id, method, params, version, capabilities):
    return {
        "jsonrpc": "2.0",
        "id": request_id,
        "method": method,
        "params": {
            **params,
            "_meta": {
                "io.modelcontextprotocol/protocolVersion": version,
                "io.modelcontextprotocol/clientCapabilities": capabilities,
                "io.modelcontextprotocol/clientInfo": CLIENT_INFO,
            },
        },
    }

Do not attach metadata once to a connection object and assume it reached the wire. Stamp and inspect the final serialized request.

Modern discovery

server/discover returns supported versions, server capabilities, instructions, cache hints, and recommended server identity. A client chooses the highest mutually supported modern version.

Discovery is optional for a modern-only client, but it is recommended on stdio. Some legacy servers accept an operation before initialization, so sending tools/list first can produce an ambiguous success. server/discover creates a clean era boundary.

The stdio compatibility probe

A dual-era stdio client sends server/discover with its preferred modern metadata before any other request. There are three outcome classes:

  1. DiscoverResult. The server is modern. Select a mutually supported version and continue with per-request metadata.
  2. Recognized modern error. The server is modern. For -32022choose from data.supported and retry with a new request id. For header or capability errors, correct the request. Do not send initialize.
  3. Ambiguous signal. An unrecognized JSON-RPC error, timeout, connection close, or empty response does not identify an era. Fail closed unless that exact peer is configured for legacy compatibility.

Recognized modern protocol errors include:

  • -32020 HeaderMismatch
  • -32021 MissingRequiredClientCapability
  • -32022 UnsupportedProtocolVersion

Recognized modern errors remain modern even when the peer is on the legacy allowlist. Once a server proves that it understands the modern error vocabulary, sending initialize would be a downgrade.

Do not treat -32601 as positive legacy evidence. It only makes an explicitly allowlisted peer eligible for one legacy probe. The same rule applies to a timeout, connection close, or empty response.

Allowlisting is operator intent, not evidence

Legacy compatibility must be an explicit property of one pinned peer configuration:

Python
client.add_server("archive", archive_transport, allow_legacy=True)

Bind that choice to the configured command or endpoint. Do not use a wildcard that lets an arbitrary server opt itself into weaker semantics. A peer without allow_legacy=True fails after an ambiguous discovery outcome and never receives initialize.

The allowlist grants permission to probe. It does not select the era. The client sends one initialize under a transport-enforced deadline, then requires all of the following:

  • a JSON-RPC 2.0 response with the matching request id;
  • exactly one result and no error;
  • a protocolVersion in the client's configured legacy revision set;
  • an object-valued capabilities field;
  • a serverInfo object with non-empty string name and version fields.

A timeout, connection close, error response, malformed result, mismatched id, or unsupported revision fails closed. Only a structurally valid positive result selects the legacy era. The code passes legacy_probe_timeout_ms to the transport adapter; a real stdio or HTTP adapter must enforce that deadline rather than merely record it.

Cache the selected era for the transport peer. Do not probe again before every call.

Legacy is a compatibility branch

Once the bounded probe returns valid positive legacy evidence, the client uses the selected legacy version exactly as defined by that revision:

  1. Verify the response envelope and correlation id.
  2. Verify the negotiated revision is in the configured legacy set.
  3. Record validated capabilities and server identity.
  4. Send notifications/initialized only after all checks pass.
  5. Use legacy request shapes for that transport lifetime.

This branch exists for interoperability with known peers. It is not the default design for new servers or new requests. If the transport restarts or its endpoint changes, discard the peer-era cache and negotiate again.

Discovering and caching tools

For each active peer, call tools/list. A modern result includes resultTypettlMsand cacheScope. Honor the freshness hint within the correct authorization context. Re-fetch after expiry or a subscribed list-change event.

Clients must treat a missing resultType from a legacy server as "complete". Do not require modern cache fields on a response from an earlier negotiated era.

The server should return deterministic ordering. The client should also sort before merging so local registry order does not depend on process startup timing.

Collision-safe namespace merge

Two servers may both expose search. Choose a declared policy:

  1. Prefix on collision. Keep the first canonical name and expose later collisions as <server>/<tool>.
  2. Reject on collision. Do not load the duplicate and surface a clear configuration error.
  3. Silent overwrite. Never use this. It hides which server receives a model-selected action.

Store both canonical and local names. The model sees the canonical name. The outgoing tools/call uses the local name the owning server declared.

Routing a call

Routing is a pure lookup:

Text
canonical tool name
  -> peer name + local tool name
  -> new JSON-RPC request id
  -> modern request metadata or explicit legacy shape
  -> matching response id

Do not send a call when its owning transport is unavailable. Reconnect or restart the transport, then re-run discovery and tools/list. Modern in-flight requests lost on a broken transport can be retried with a new JSON-RPC id when the operation's safety policy permits it.

Notifications and subscriptions

Modern list and resource changes arrive only on a client-opened subscriptions/listen stream. The client sends the notification filter, waits for notifications/subscriptions/acknowledgedand correlates events with the listen request id in notification metadata.

On disconnect, open a new listen request and refetch relevant lists or resources. Modern streams do not resume with Last-Event-ID.

No server-initiated requests

Modern servers do not call the client with independent JSON-RPC requests for sampling, elicitation, or roots. They return input_requiredand the client retries the original request after fulfilling the embedded input requests.

Do not block the peer's response reader while fulfilling input. Preserve correlation and create a new JSON-RPC id for the retry.

Use It

code/main.py uses in-process peer functions so the protocol decisions stay visible. It connects to two modern peers and one intentionally allowlisted legacy peer, then merges and routes their tools. The transport callable receives a timeout budget so the compatibility branch cannot hide an unbounded probe.

Terminal
cd code
python3 main.py
python3 -m unittest discover tests -v

The tests prove boundaries that normal demos miss:

  • modern requests repeat metadata;
  • -32022 retries modern discovery without initialization;
  • recognized modern errors never downgrade, even for an allowlisted peer;
  • timeouts, connection closes, empty responses, and unrecognized errors do not trigger initialize without an allowlist;
  • an allowlisted peer becomes legacy only after a valid, supported initialize result;
  • malformed and unsupported legacy results leave the peer unavailable;
  • a successfully selected era is cached for the transport lifetime.

Ship It

This lesson ships outputs/skill-mcp-client-harness.md. It scaffolds modern request stamping, stdio era negotiation, deterministic namespace merge, routing, and a fail-closed legacy compatibility branch.

Exercises

  1. Make a fake server return -32022 with no mutually supported version. Confirm the client fails instead of sending initialize.
  2. Allowlist a fake legacy server, make its bounded initialize probe time out, and prove the peer stays unknown and unavailable.
  3. Add cacheScope: "private" tool lists for two authorization contexts. Confirm the client never shares one context's cached result with the other.
  4. Change the collision policy to rejection and make startup fail with both peer names in the error.
  5. Add a finite subscriptions/listen simulator. On stream loss, re-listen with a new request id and refetch tools.

Key Terms

TermMeaning
PeerClient-side record for one server transport and its discovered data
Protocol eraModern per-request metadata or legacy initialization semantics
Discovery probeInitial server/discover used to identify the stdio era
Recognized modern errorError that proves modern behavior and forbids legacy fallback
Legacy allowlistOperator configuration permitting one bounded compatibility probe for a pinned peer
Positive legacy evidenceValid, correlated initialize result for an explicitly supported legacy revision
Merged namespaceCanonical tool names across all active peers
Collision policyPrefix or reject rule for duplicate tool names
Era cacheSelected modern or legacy behavior stored for one transport peer
Transport recoveryRestart or reconnect, rediscover, relist, and retry safely with a new id

Further Reading

Check what you learned

6 questions. Answer each one to see why.

Question 1 of 60 correct

What should a dual-era stdio client send first?

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""Phase 13 Lesson 08: a stateless multi-server MCP client.
Lesson: phases/13-tools-and-protocols/08-building-an-mcp-client/docs/en.md
Specification: https://modelcontextprotocol.io/specification/2026-07-28/
Demonstrates discovery, fail-closed legacy probing, deterministic merge, and routing.
Run: python3 main.py
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Callable


PROTOCOL_VERSION = "2026-07-28"
LEGACY_VERSION = "2025-11-25"
VERSION_KEY = "io.modelcontextprotocol/protocolVersion"
CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities"
CLIENT_INFO_KEY = "io.modelcontextprotocol/clientInfo"
SERVER_INFO_KEY = "io.modelcontextprotocol/serverInfo"
RECOGNIZED_MODERN_ERRORS = {-32020, -32021, -32022}

CLIENT_INFO = {"name": "lesson-08-client", "version": "2.0.0"}
CLIENT_CAPABILITIES: dict[str, Any] = {"extensions": {}}

Transport = Callable[[dict[str, Any], int | None], dict[str, Any] | None]


class RpcFault(Exception):
    def __init__(self, code: int, message: str, data: Any | None = None) -> None:
        super().__init__(message)
        self.code = code
        self.data = data


def request_meta(
    version: str,
    capabilities: dict[str, Any] | None = None,
) -> dict[str, Any]:
    return {
        VERSION_KEY: version,
        CAPABILITIES_KEY: CLIENT_CAPABILITIES.copy() if capabilities is None else capabilities,
        CLIENT_INFO_KEY: CLIENT_INFO.copy(),
    }


def modern_request(
    request_id: int | str,
    method: str,
    params: dict[str, Any] | None,
    version: str,
    capabilities: dict[str, Any] | None = None,
) -> dict[str, Any]:
    body_params = dict(params or {})
    body_params["_meta"] = request_meta(version, capabilities)
    return {"jsonrpc": "2.0", "id": request_id, "method": method, "params": body_params}


def legacy_request(
    request_id: int | str,
    method: str,
    params: dict[str, Any] | None = None,
) -> dict[str, Any]:
    return {"jsonrpc": "2.0", "id": request_id, "method": method, "params": dict(params or {})}


def rpc_error(
    request_id: int | str | None,
    code: int,
    message: str,
    data: Any | None = None,
) -> dict[str, Any]:
    error: dict[str, Any] = {"code": code, "message": message}
    if data is not None:
        error["data"] = data
    return {"jsonrpc": "2.0", "id": request_id, "error": error}


def complete(
    server_info: dict[str, str],
    payload: dict[str, Any],
    *,
    ttl_ms: int | None = None,
    cache_scope: str = "private",
) -> dict[str, Any]:
    result = {
        "resultType": "complete",
        **payload,
        "_meta": {SERVER_INFO_KEY: server_info.copy()},
    }
    if ttl_ms is not None:
        result["ttlMs"] = ttl_ms
        result["cacheScope"] = cache_scope
    return result


def decode_rpc_response(
    response: dict[str, Any],
    expected_id: int | str,
) -> tuple[str, dict[str, Any]]:
    response_id = response.get("id")
    if (
        response.get("jsonrpc") != "2.0"
        or type(response_id) not in (int, str)
        or type(response_id) is not type(expected_id)
        or response_id != expected_id
    ):
        raise RuntimeError("invalid JSON-RPC response envelope")
    has_result = "result" in response
    has_error = "error" in response
    if has_result == has_error:
        raise RuntimeError("JSON-RPC response must contain exactly one of result or error")
    if has_result:
        result = response["result"]
        if not isinstance(result, dict):
            raise RuntimeError("JSON-RPC result must be an object")
        return "result", result
    error = response["error"]
    if not isinstance(error, dict):
        raise RuntimeError("JSON-RPC error must be an object")
    code = error.get("code")
    if not isinstance(code, int) or isinstance(code, bool) or not isinstance(error.get("message"), str):
        raise RuntimeError("JSON-RPC error requires an integer code and string message")
    return "error", error


def validate_modern_request(message: dict[str, Any], supported: list[str]) -> None:
    if message.get("jsonrpc") != "2.0" or not isinstance(message.get("method"), str):
        raise RpcFault(-32600, "Invalid Request")
    params = message.get("params")
    if not isinstance(params, dict) or not isinstance(params.get("_meta"), dict):
        raise RpcFault(-32602, "Modern params._meta is required")
    meta = params["_meta"]
    requested = meta.get(VERSION_KEY)
    if not isinstance(requested, str):
        raise RpcFault(-32602, f"{VERSION_KEY} is required")
    if requested not in supported:
        raise RpcFault(
            -32022,
            "Unsupported protocol version",
            {"requested": requested, "supported": supported.copy()},
        )
    if not isinstance(meta.get(CAPABILITIES_KEY), dict):
        raise RpcFault(-32602, f"{CAPABILITIES_KEY} is required")


class ModernFakeServer:
    def __init__(
        self,
        name: str,
        tools: list[dict[str, Any]],
        capabilities: dict[str, Any] | None = None,
        supported_versions: list[str] | None = None,
    ) -> None:
        self.server_info = {"name": name, "version": "2.0.0"}
        self.tools = sorted(tools, key=lambda tool: tool["name"])
        self.capabilities = capabilities or {"tools": {"listChanged": False}}
        self.supported_versions = supported_versions or [PROTOCOL_VERSION]
        self.received: list[dict[str, Any]] = []
        self.timeouts_ms: list[int | None] = []

    def __call__(
        self,
        message: dict[str, Any],
        timeout_ms: int | None = None,
    ) -> dict[str, Any] | None:
        self.received.append(message)
        self.timeouts_ms.append(timeout_ms)
        if "id" not in message:
            return None
        request_id = message["id"]
        try:
            validate_modern_request(message, self.supported_versions)
            method = message["method"]
            params = message["params"]
            if method == "server/discover":
                result = complete(
                    self.server_info,
                    {
                        "supportedVersions": self.supported_versions.copy(),
                        "capabilities": self.capabilities.copy(),
                        "instructions": f"Tools provided by {self.server_info['name']}.",
                    },
                    ttl_ms=3_600_000,
                    cache_scope="public",
                )
            elif method == "tools/list":
                result = complete(
                    self.server_info,
                    {"tools": self.tools.copy()},
                    ttl_ms=30_000,
                    cache_scope="public",
                )
            elif method == "tools/call":
                name = params.get("name")
                if not isinstance(name, str):
                    raise RpcFault(-32602, "tools/call requires name")
                declared = {tool["name"] for tool in self.tools}
                result = complete(
                    self.server_info,
                    {
                        "content": [
                            {
                                "type": "text",
                                "text": (
                                    f"[{self.server_info['name']}] {name} ran"
                                    if name in declared
                                    else f"Unknown tool: {name}"
                                ),
                            }
                        ],
                        "isError": name not in declared,
                    },
                )
            else:
                raise RpcFault(-32601, f"Method not found: {method}")
            return {"jsonrpc": "2.0", "id": request_id, "result": result}
        except RpcFault as exc:
            return rpc_error(request_id, exc.code, str(exc), exc.data)


class LegacyFakeServer:
    def __init__(self, name: str, tools: list[dict[str, Any]]) -> None:
        self.name = name
        self.tools = sorted(tools, key=lambda tool: tool["name"])
        self.initialized = False
        self.received: list[dict[str, Any]] = []
        self.timeouts_ms: list[int | None] = []

    def __call__(
        self,
        message: dict[str, Any],
        timeout_ms: int | None = None,
    ) -> dict[str, Any] | None:
        self.received.append(message)
        self.timeouts_ms.append(timeout_ms)
        method = message.get("method")
        if method == "server/discover":
            return rpc_error(message.get("id"), -32601, "Method not found")
        if method == "initialize":
            self.initialized = True
            return {
                "jsonrpc": "2.0",
                "id": message["id"],
                "result": {
                    "protocolVersion": LEGACY_VERSION,
                    "capabilities": {"tools": {}},
                    "serverInfo": {"name": self.name, "version": "1.0.0"},
                },
            }
        if method == "notifications/initialized":
            return None
        if not self.initialized:
            return rpc_error(message.get("id"), -32002, "Server not initialized")
        if method == "tools/list":
            return {"jsonrpc": "2.0", "id": message["id"], "result": {"tools": self.tools.copy()}}
        if method == "tools/call":
            name = message.get("params", {}).get("name")
            return {
                "jsonrpc": "2.0",
                "id": message["id"],
                "result": {
                    "content": [{"type": "text", "text": f"[{self.name}/legacy] {name} ran"}],
                    "isError": False,
                },
            }
        return rpc_error(message.get("id"), -32601, f"Method not found: {method}")


@dataclass
class Peer:
    name: str
    transport: Transport
    allow_legacy: bool = False
    era: str = "unknown"
    protocol_version: str | None = None
    capabilities: dict[str, Any] = field(default_factory=dict)
    server_info: dict[str, Any] = field(default_factory=dict)
    tools: list[dict[str, Any]] = field(default_factory=list)
    available: bool = False


@dataclass(frozen=True)
class MergedTool:
    canonical_name: str
    peer_name: str
    local_name: str
    description: str


class MultiServerClient:
    def __init__(
        self,
        *,
        supported_modern: tuple[str, ...] = (PROTOCOL_VERSION,),
        supported_legacy: tuple[str, ...] = (LEGACY_VERSION,),
        probe_version: str | None = None,
        discovery_timeout_ms: int = 1_000,
        legacy_probe_timeout_ms: int = 1_000,
    ) -> None:
        if not supported_modern or not supported_legacy:
            raise ValueError("at least one modern and legacy version must be configured")
        if discovery_timeout_ms <= 0 or legacy_probe_timeout_ms <= 0:
            raise ValueError("probe timeouts must be positive")
        self.supported_modern = supported_modern
        self.supported_legacy = supported_legacy
        self.probe_version = probe_version or supported_modern[0]
        self.discovery_timeout_ms = discovery_timeout_ms
        self.legacy_probe_timeout_ms = legacy_probe_timeout_ms
        self.client_capabilities = CLIENT_CAPABILITIES.copy()
        self.peers: dict[str, Peer] = {}
        self.registry: dict[str, MergedTool] = {}
        self._next_request_id = 1

    def _new_id(self) -> int:
        request_id = self._next_request_id
        self._next_request_id += 1
        return request_id

    def add_server(
        self,
        name: str,
        transport: Transport,
        *,
        allow_legacy: bool = False,
    ) -> None:
        self.peers[name] = Peer(
            name=name,
            transport=transport,
            allow_legacy=allow_legacy,
        )

    @staticmethod
    def _send(
        peer: Peer,
        message: dict[str, Any],
        timeout_ms: int | None = None,
    ) -> dict[str, Any] | None:
        return peer.transport(message, timeout_ms)

    def _mutual_version(self, advertised: list[Any]) -> str | None:
        common = [version for version in advertised if version in self.supported_modern]
        return sorted(common, reverse=True)[0] if common else None

    def _activate_modern(self, peer: Peer, result: dict[str, Any], version: str) -> None:
        if result.get("resultType") != "complete":
            raise RuntimeError(f"{peer.name}: modern discovery omitted resultType")
        peer.era = "modern"
        peer.protocol_version = version
        peer.capabilities = result.get("capabilities", {})
        peer.server_info = result.get("_meta", {}).get(SERVER_INFO_KEY, {})
        peer.available = True

    def _probe_legacy(self, peer: Peer, trigger: str) -> None:
        if not peer.allow_legacy:
            raise RuntimeError(
                f"{peer.name}: {trigger}; legacy compatibility is not allowlisted"
            )
        request_id = self._new_id()
        initialize = legacy_request(
            request_id,
            "initialize",
            {
                "protocolVersion": self.supported_legacy[0],
                "capabilities": self.client_capabilities.copy(),
                "clientInfo": CLIENT_INFO.copy(),
            },
        )
        try:
            response = self._send(peer, initialize, self.legacy_probe_timeout_ms)
        except (TimeoutError, ConnectionError) as exc:
            raise RuntimeError(f"{peer.name}: bounded legacy probe failed closed") from exc
        if not isinstance(response, dict):
            raise RuntimeError(f"{peer.name}: bounded legacy probe returned no result")
        kind, payload = decode_rpc_response(response, request_id)
        if kind != "result":
            raise RuntimeError(f"{peer.name}: legacy initialize returned an error")
        result = payload
        version = result.get("protocolVersion")
        capabilities = result.get("capabilities")
        server_info = result.get("serverInfo")
        valid_server_info = (
            isinstance(server_info, dict)
            and isinstance(server_info.get("name"), str)
            and bool(server_info["name"])
            and isinstance(server_info.get("version"), str)
            and bool(server_info["version"])
        )
        if version not in self.supported_legacy:
            raise RuntimeError(f"{peer.name}: unsupported legacy protocol revision")
        if not isinstance(capabilities, dict) or not valid_server_info:
            raise RuntimeError(f"{peer.name}: malformed legacy initialize result")
        peer.era = "legacy"
        peer.protocol_version = version
        peer.capabilities = capabilities
        peer.server_info = server_info
        peer.available = True
        self._send(
            peer,
            {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}
        )

    def _connect_peer(self, peer: Peer) -> None:
        if peer.available and peer.era in {"modern", "legacy"}:
            return
        request_id = self._new_id()
        probe = modern_request(
            request_id,
            "server/discover",
            {},
            self.probe_version,
            self.client_capabilities,
        )
        try:
            response = self._send(peer, probe, self.discovery_timeout_ms)
        except (TimeoutError, ConnectionError) as exc:
            self._probe_legacy(peer, type(exc).__name__)
            return

        if response is None:
            self._probe_legacy(peer, "empty discovery response")
            return
        if not isinstance(response, dict):
            raise RuntimeError(f"{peer.name}: malformed discovery response")
        kind, payload = decode_rpc_response(response, request_id)
        if kind == "result":
            advertised = payload.get("supportedVersions", [])
            if not isinstance(advertised, list) or not all(
                isinstance(version, str) for version in advertised
            ):
                raise RuntimeError(f"{peer.name}: malformed modern discovery result")
            selected = self._mutual_version(advertised)
            if selected is None:
                raise RuntimeError(f"{peer.name}: no mutually supported modern version")
            self._activate_modern(peer, payload, selected)
            return

        code = payload["code"]
        if code in RECOGNIZED_MODERN_ERRORS:
            if code != -32022:
                raise RuntimeError(f"{peer.name}: correct modern request error {code} before retrying")
            data = payload.get("data")
            advertised = data.get("supported", []) if isinstance(data, dict) else []
            selected = self._mutual_version(advertised)
            if selected is None:
                raise RuntimeError(f"{peer.name}: no mutually supported modern version")
            retry_id = self._new_id()
            retry = modern_request(
                retry_id,
                "server/discover",
                {},
                selected,
                self.client_capabilities,
            )
            try:
                retried = self._send(peer, retry, self.discovery_timeout_ms)
            except (TimeoutError, ConnectionError) as exc:
                raise RuntimeError(f"{peer.name}: proven-modern discovery retry failed") from exc
            if not isinstance(retried, dict):
                raise RuntimeError(f"{peer.name}: proven-modern discovery retry returned no result")
            retry_kind, retry_payload = decode_rpc_response(retried, retry_id)
            if retry_kind != "result":
                raise RuntimeError(f"{peer.name}: proven-modern discovery retry returned an error")
            self._activate_modern(peer, retry_payload, selected)
            return

        self._probe_legacy(peer, f"unrecognized discovery error {code}")

    def connect_all(self) -> None:
        for peer_name in sorted(self.peers):
            self._connect_peer(self.peers[peer_name])

    def _request(self, peer: Peer, method: str, params: dict[str, Any]) -> dict[str, Any]:
        request_id = self._new_id()
        if peer.era == "modern":
            message = modern_request(
                request_id,
                method,
                params,
                peer.protocol_version or PROTOCOL_VERSION,
                self.client_capabilities,
            )
        elif peer.era == "legacy":
            message = legacy_request(request_id, method, params)
        else:
            raise RuntimeError(f"{peer.name}: protocol era not selected")
        response = self._send(peer, message)
        if not isinstance(response, dict):
            raise RuntimeError(f"{peer.name}: missing response")
        kind, payload = decode_rpc_response(response, request_id)
        if kind != "result":
            raise RuntimeError(f"{peer.name}: RPC error {payload}")
        result = dict(payload)
        if peer.era == "modern" and "resultType" not in result:
            raise RuntimeError(f"{peer.name}: modern result omitted resultType")
        if peer.era == "legacy":
            result.setdefault("resultType", "complete")
        return result

    def discover_tools(self) -> None:
        for peer_name in sorted(self.peers):
            peer = self.peers[peer_name]
            if peer.available:
                result = self._request(peer, "tools/list", {})
                peer.tools = sorted(result.get("tools", []), key=lambda tool: tool["name"])

    def merge(self, policy: str = "prefix-on-collision") -> None:
        if policy not in {"prefix-on-collision", "reject"}:
            raise ValueError("policy must be prefix-on-collision or reject")
        self.registry.clear()
        for peer_name in sorted(self.peers):
            peer = self.peers[peer_name]
            for tool in peer.tools:
                local_name = tool["name"]
                canonical_name = local_name
                if canonical_name in self.registry:
                    if policy == "reject":
                        continue
                    canonical_name = f"{peer.name}/{local_name}"
                    if canonical_name in self.registry:
                        raise ValueError(f"canonical collision: {canonical_name}")
                self.registry[canonical_name] = MergedTool(
                    canonical_name=canonical_name,
                    peer_name=peer.name,
                    local_name=local_name,
                    description=tool.get("description", ""),
                )
        self.registry = dict(sorted(self.registry.items()))

    def call(self, canonical_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
        merged = self.registry.get(canonical_name)
        if merged is None:
            return {
                "resultType": "complete",
                "content": [{"type": "text", "text": f"Unknown tool: {canonical_name}"}],
                "isError": True,
            }
        peer = self.peers[merged.peer_name]
        if not peer.available:
            return {
                "resultType": "complete",
                "content": [{"type": "text", "text": f"Transport unavailable: {peer.name}"}],
                "isError": True,
            }
        return self._request(
            peer,
            "tools/call",
            {"name": merged.local_name, "arguments": arguments},
        )


def tool(name: str, description: str) -> dict[str, Any]:
    return {
        "name": name,
        "description": description,
        "inputSchema": {"type": "object", "properties": {}, "required": []},
    }


def main() -> None:
    notes = ModernFakeServer("notes", [tool("search", "Search notes"), tool("create", "Create note")])
    files = ModernFakeServer("files", [tool("search", "Search files"), tool("read", "Read file")])
    archive = LegacyFakeServer("archive", [tool("search", "Search archive"), tool("restore", "Restore item")])

    client = MultiServerClient()
    client.add_server("notes", notes)
    client.add_server("files", files)
    client.add_server("archive", archive, allow_legacy=True)

    client.connect_all()
    client.discover_tools()
    client.merge()

    print("MCP client peers")
    for peer_name, peer in sorted(client.peers.items()):
        print(f"  {peer_name:8s} era={peer.era:6s} version={peer.protocol_version}")
    print("\nMerged tools")
    for canonical_name, merged in client.registry.items():
        print(f"  {canonical_name:20s} -> {merged.peer_name}:{merged.local_name}")
    print("\nCalls")
    for name in ("create", "read", "notes/search", "search", "restore"):
        result = client.call(name, {})
        print(f"  {name:20s} -> {result['content'][0]['text']}")
    print("\nNo modern protocol sessions were created.")


if __name__ == "__main__":
    main()