Skip to content

Clients

Stable

Covered by the 1.0 API freeze (proposal 0029): no breaking change before 2.0.

Broker

Broker(servers: Mapping[str, Any], *, budget: Budget | None = None, tokenizer: str | TokenCounter | None = None, deadline_s: float = 60.0, elicitation_handler: Any = None, sampling_handler: Any = None, roots: Any = None, approver: Approver | None = None, failure_threshold: int = 3, cooldown_s: float = 30.0, search_results: int = 5, connect_timeout_s: float = 15.0, auth: Mapping[str, Any] | None = None)

Connect to many servers as one. Use as async with Broker({...}) as broker:.

servers maps a local id to a target: an http(s) URL, a server file (path.py[:name]), a command line (string or list), or a FastMCP or OunceServer object (in-process).

unavailable property

unavailable: dict[str, str]

Servers that could not be reached, with a short reason.

instructions

instructions() -> dict[str, str]

Each server's instructions, kept apart and labeled; never merge them into the host's own instructions (CLI-8).

tools async

tools(*, refresh: bool = False) -> list[BrokerTool]

Every reachable server's tools, namespaced <server>.<tool>.

host_tools async

host_tools() -> tuple[str, list[dict[str, Any]]]

What to give the model: ("direct", every definition) while they fit Budget.startup_tokens, else ("search", three meta-tool definitions).

handle async

handle(meta_tool: str, arguments: Mapping[str, Any]) -> Any

Answer one of the three meta-tools from host_tools() in search mode.

call async

call(name: str, arguments: Mapping[str, Any] | None = None, *, deadline_s: float | None = None, caused_by: BrokerResult | None = None) -> BrokerResult

Call <server>.<tool>. caused_by is the result that led to this call, if any; it decides whether the host must approve (CLI-8).

BrokerResult dataclass

BrokerResult(name: str, server: str, text: str, structured: Any, is_error: bool, tokens: int, tokenizer: str, meta: dict[str, Any] = dict(), untrusted: bool = True)

A tool result as the host should handle it. text is what the model reads; untrusted is always true: server output is data, never instructions.

for_model

for_model() -> str

The text with its provenance, for hosts that pass results to the model.

OunceOAuth

OunceOAuth(mcp_url: str | None = None, *, client_id: str | None = None, client_secret: str | None = None, client_metadata_url: str | None = None, allow_dynamic: bool = True, **kwargs: Any)

Bases: OAuth

FastMCP's OAuth with the SEC-10 registration order.

Only the chosen method's settings reach the flow: with a client_id, a client_metadata_url is ignored. Other arguments (scopes, client_name, token_storage, callback_port...) are FastMCP's.

registration_method

registration_method(*, client_id: str | None = None, client_metadata_url: str | None = None, allow_dynamic: bool = True) -> Registration

The registration a client with these settings uses, in the MCP spec's order.