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.
Learning Objectives
- Build every MCP
2026-07-28request with current metadata. - Probe stdio servers with
server/discoverand select a mutually supported version. - Authorize a bounded legacy probe only for explicitly allowlisted peers.
- Accept a legacy era only after validating a positive
initializeresult 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
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:
- DiscoverResult. The server is modern. Select a mutually supported version and continue with per-request metadata.
- Recognized modern error. The server is modern. For
-32022choose fromdata.supportedand retry with a new request id. For header or capability errors, correct the request. Do not sendinitialize. - 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:
-32020HeaderMismatch-32021MissingRequiredClientCapability-32022UnsupportedProtocolVersion
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:
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.0response with the matching request id; - exactly one
resultand noerror; - a
protocolVersionin the client's configured legacy revision set; - an object-valued
capabilitiesfield; - a
serverInfoobject with non-empty stringnameandversionfields.
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:
- Verify the response envelope and correlation id.
- Verify the negotiated revision is in the configured legacy set.
- Record validated capabilities and server identity.
- Send
notifications/initializedonly after all checks pass. - 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:
- Prefix on collision. Keep the first canonical name and expose later collisions as
<server>/<tool>. - Reject on collision. Do not load the duplicate and surface a clear configuration error.
- 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:
canonical tool name
-> peer name + local tool name
-> new JSON-RPC request id
-> modern request metadata or explicit legacy shape
-> matching response idDo 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.
cd code
python3 main.py
python3 -m unittest discover tests -vThe tests prove boundaries that normal demos miss:
- modern requests repeat metadata;
-32022retries 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
initializewithout an allowlist; - an allowlisted peer becomes legacy only after a valid, supported
initializeresult; - 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
- Make a fake server return
-32022with no mutually supported version. Confirm the client fails instead of sendinginitialize. - Allowlist a fake legacy server, make its bounded
initializeprobe time out, and prove the peer staysunknownand unavailable. - Add
cacheScope: "private"tool lists for two authorization contexts. Confirm the client never shares one context's cached result with the other. - Change the collision policy to rejection and make startup fail with both peer names in the error.
- Add a finite
subscriptions/listensimulator. On stream loss, re-listen with a new request id and refetch tools.
Key Terms
| Term | Meaning |
|---|---|
| Peer | Client-side record for one server transport and its discovered data |
| Protocol era | Modern per-request metadata or legacy initialization semantics |
| Discovery probe | Initial server/discover used to identify the stdio era |
| Recognized modern error | Error that proves modern behavior and forbids legacy fallback |
| Legacy allowlist | Operator configuration permitting one bounded compatibility probe for a pinned peer |
| Positive legacy evidence | Valid, correlated initialize result for an explicitly supported legacy revision |
| Merged namespace | Canonical tool names across all active peers |
| Collision policy | Prefix or reject rule for duplicate tool names |
| Era cache | Selected modern or legacy behavior stored for one transport peer |
| Transport recovery | Restart 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.
What should a dual-era stdio client send first?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""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()