Module tools 

Calling tools on other people’s servers.

The security decision this module exists to make

MCP servers advertise their tools with annotations: readOnlyHint, destructiveHint, idempotentHint. They read like a safety contract. The specification is explicit that they are not:

Clients MUST consider tool annotations to be untrusted unless they come from trusted servers.

That warning lands harder here than in most runtimes, because of how the declarations compose. readOnlyHint: true would mean Effect::mutates is false; a non-mutating effect defaults to Recovery::Retry; and a retried call is a second real call. So a server that marks its own money-moving tool read-only could arrange for that tool to be retried after a timeout — choosing, from the far side of the trust boundary, the one condition under which this runtime performs something twice.

So safety is not taken from the wire. It comes from a ToolCatalog the operator writes, and:

• A tool absent from the catalogue cannot be called at all. Fail closed: an unknown tool is one nobody has reasoned about, and discovering tools at runtime is exactly how an agent acquires authority nobody granted.
• Advertised hints are recorded and compared, never obeyed. A server claiming more safety than the operator granted is not a nuisance to normalise away — it is a signal, and it is reported.

What is not second-guessed

The tool’s output. It arrives as Tainted and untrusted, like every other effect result, because it is the outside world’s data. Nothing in the catalogue can change that: the catalogue governs authority, not provenance.

Re-exports

pub use rmcp;

Modules

serve

Serving MCP: the other direction from the host side of this module, where a model’s host calls in and a governed run happens. Serving MCP.

serve_http

Serving MCP over Streamable HTTP.

Structs

Advertised

What a server said about its own tool.

Discovered

What a server says one of its tools is: a draft for a grant, and the reference a reviewed grant is compared with.

McpAccess

Operator grants for MCP context capabilities.

McpClient

A connected MCP server.

McpDataSafety

Data-flow limits for one MCP prompt or resource grant.

McpPrompt

One exact, operator-granted prompts/get request.

McpResource

One exact, operator-granted resources/read request.

McpTask

A stable asynchronous task handle returned by an MCP operation.

McpTaskCancel

Cooperative cancellation of an MCP task.

McpTaskPoll

One journaled tasks/get observation.

McpTaskSnapshot

McpTaskUpdate

Answers outstanding input requests on an MCP task.

ToolBox

A set of typed tools, dispatched by name once, here.

ToolCall

One call to one tool.

ToolCatalog

The tools this plane may call, and what the operator says about each.

ToolId

Which tool, on which server.

ToolRouter

Which client reaches which server.

ToolSafety

What the operator says about a tool.

Enums

Destination

Where a ToolClient sends a call.

Drift

Where a server’s tool has moved away from the grant an operator reviewed.

McpTaskState

TaskRetention

How long a server says it will keep a task.

ToolError

Why a tool call could not be made, or did not work.

ToolFailure

What a tool body knows about whether the world changed.

Constants

AGENT_SERVER

The reserved server that names agents on this plane rather than a transport.

MCP_REVISION

The MCP revision this plane serves and offers.

TOOL_CALL_KIND

The effect kind a call to an MCP tool is announced under.

TOOL_SCHEME

The scheme a manifest grant is written in.

Traits

Tool

One tool: its name, its arguments, and what it does.

ToolClient

Transports a tool call. Implemented by the MCP adapter, or by anything else.

Functions

closed_schema

schema, narrowed so a provider’s strict mode can hold a model to it.

strict_schema

The schema of T, made ready for strict decoding as a typed tool’s is.