Struct McpClient 

pub struct McpClient { /* private fields */ }

A connected (and, after McpClient::initialize, handshaken) remote MCP server over Streamable HTTP.

Implementations

impl McpClient

pub fn connect( name: &str, endpoint: &str, headers: Vec<(String, String)>, timeout: Duration, ) -> Result<McpClient, McpError>

Connect to a remote MCP server over Streamable HTTP (RFC 0004). endpoint is https://… / http://… / unix:/path / vsock:cid:port. headers are caller-owned request headers (auth/framing — resolved secret values, never templates or logs). No process is spawned (RFC 0012). Call Self::initialize before any tool/resource call.

pub fn connect_signed( name: &str, endpoint: &str, headers: Vec<(String, String)>, timeout: Duration, signer: Option<Arc<dyn RequestSigner>>, ) -> Result<McpClient, McpError>

Self::connect with an optional per-request AAuth signer (RFC 0023) — every outbound request to this server is signed. None = unsigned (the connect default).

pub fn with_client_info(self, info: Implementation) -> McpClient

Override the client identity sent to servers (name + version). agentd sets its own; other hosts of the mcp crate set theirs.

pub fn with_elicitation(self, handler: Arc<dyn Handler>) -> McpClient

Answer server→client elicitation requests through handler: a server may ask the operator a question mid-call and get a typed answer back. Declares the elicitation client capability, so a server only asks when we can actually deliver the question to a human.

pub fn with_roots(self, handler: Arc<dyn Handler>) -> McpClient

Answer roots/list through handler — the URI roots this client permits a server to operate on. Declares the roots capability.

pub fn with_tasks(self) -> McpClient

Advertise support for the tasks extension (io.modelcontextprotocol/ tasks) — a server may then return an async task handle from a supported request instead of blocking (poll it with Self::get_task).

pub fn with_identity(self, identity: ClientIdentity) -> McpClient

Attach a mutual-TLS client identity (a mounted cert chain + key) for a https:// endpoint. A no-op on non-TLS endpoints (the identity is only presented during the TLS handshake). RFC 0012 §3.7: the key never leaves the process (see net::tls).

pub fn name(&self) -> &str

pub fn capabilities(&self) -> &ServerCapabilities

pub fn set_tool_meta(&mut self, meta: Value)

Set the _meta stamped onto every tools/call (e.g. the run id, for retry dedup). Call after initialize. RFC 0011 §idempotency.

pub fn initialize(&mut self) -> Result<(), McpError>

MCP lifecycle handshake: initialize → store capabilities → notifications/initialized. Uses the default per-request timeout.

pub fn initialize_within(&mut self, timeout: Duration) -> Result<(), McpError>

Self::initialize with a caller-supplied timeout for the initialize round-trip (the SHORT management bound, RFC 0016 §10). Used by the hot-reload re-handshake, which adds a server ON the reactor thread mid-loop: a slow-but-alive added server must not block the reactor (and starve the liveness heartbeat) for the full ~60s — a timeout is a contained mcp.connect.fail (the server is simply absent, RFC 0007 / RFC 0017 §5.3).

pub fn era(&self) -> Era

The protocol era established on connect (legacy handshake vs modern stateless). Governs how each request is built.

pub fn protocol_version(&self) -> Option<&str>

The protocol version negotiated with the server (None before connect). Sent as MCP-Protocol-Version on every subsequent request.

pub fn list_tools(&self) -> Result<Vec<Tool>, McpError>

tools/list, following cursor pagination to completion. Empty when the server doesn’t advertise tools. Uses the default per-request timeout.

pub fn list_tools_within( &self, _timeout: Duration, ) -> Result<Vec<Tool>, McpError>

tools/list with a caller-supplied per-request timeout (the SHORT management bound, RFC 0016 §10) instead of the default ~60s. Used by the reactor-thread management path (hot-reload re-handshake, claim coordination re-validation) so a slow-but-alive coordination server cannot outrun the liveness heartbeat. A timeout surfaces as the usual McpError::Timeout, which the callers already treat as a best-effort failure. The timeout is applied to EACH page (each pagination round-trip is bounded), matching the per-request contract of Self::request_with_timeout.

pub fn call_tool( &self, name: &str, arguments: Option<Value>, ) -> Result<CallToolResult, McpError>

tools/call. The returned CallToolResult carries isError (a tool-domain failure observation) — distinct from an Err here, which is a transport/protocol failure (RFC 0004 §isError).

pub fn call_tool_with_meta( &self, name: &str, arguments: Option<Value>, extra_meta: Value, ) -> Result<CallToolResult, McpError>

tools/call with per-call _meta merged on top of the persistent Self::set_tool_meta for this one call only — without mutating the stored meta. Used by the work-claim client (RFC 0019 §3 / RFC 0015 §5.6), where agent/claim_key is per-item and must ride the individual call, never the persistent stamp. extra_meta (an object) wins key-by-key over the persistent meta; a non-object extra_meta replaces it. The persistent meta is left untouched.

pub fn call_tool_with_meta_within( &self, name: &str, arguments: Option<Value>, extra_meta: Value, timeout: Duration, ) -> Result<CallToolResult, McpError>

tools/call with per-call _meta AND a caller-supplied per-request timeout (the SHORT management bound, RFC 0016 §10) instead of the default ~60s. Used by the reactor-thread lease management path (claim renew/ack/release) — a slow coordination server must not block the reactor past the liveness staleness window. Behaviour is otherwise identical to Self::call_tool_with_meta; a timeout surfaces as McpError::Timeout, which the lease callers already treat as a best-effort failure. The data path (subagent tool calls) never uses this — it keeps the default timeout.

pub fn list_resources(&self) -> Result<Vec<Resource>, McpError>

pub fn list_prompts(&self) -> Result<Vec<Prompt>, McpError>

prompts/list, following cursor pagination to completion. Empty when the server doesn’t advertise prompts.

pub fn get_prompt( &self, name: &str, arguments: Option<Value>, ) -> Result<GetPromptResult, McpError>

prompts/get — render the named prompt template with arguments (a flat string map). Gated on the server advertising prompts.

pub fn complete( &self, reference: Value, argument: Value, ) -> Result<CompleteResult, McpError>

completion/complete — argument autocompletion for a prompt / resource- template reference. Gated on the server advertising completions.

pub fn list_resource_templates(&self) -> Result<Vec<ResourceTemplate>, McpError>

resources/templates/list, paginated. Empty when the server doesn’t advertise resources.

pub fn ping(&self) -> Result<(), McpError>

ping — a liveness round-trip (RFC 0004 §utilities). Returns Ok(()) if the server answers within the default timeout.

pub fn as_task(&self, result: &Value) -> Option<Task>

If result is a task handle (resultType: "task", the async shape a task-augmented request returns instead of blocking), parse it. Enable the extension with Self::with_tasks; poll the handle with Self::get_task.

pub fn get_task(&self, task_id: &str) -> Result<Task, McpError>

tasks/get — poll one async task’s current state (the tasks extension).

pub fn update_task( &self, task_id: &str, input_responses: Value, ) -> Result<(), McpError>

tasks/update — supply inputResponses for a task in input_required (the MRTR fulfilment path). Acknowledged with an empty result.

pub fn cancel_task(&self, task_id: &str) -> Result<(), McpError>

tasks/cancel — request cancellation of a task (cooperative; the server may still reach a non-cancelled terminal state). Acknowledged with an empty result.

pub fn await_task( &self, task_id: &str, deadline: Instant, ) -> Result<Task, McpError>

Poll tasks/get until the task reaches a terminal status or deadline, honoring the server’s pollIntervalMs (bounded to a sane window). Returns the terminal Task (the caller reads result/error); a task that stops on input_required is returned so the caller can drive the MRTR loop.

pub fn read_resource(&self, uri: &str) -> Result<ReadResourceResult, McpError>

pub fn read_resource_within( &self, uri: &str, _timeout: Duration, ) -> Result<ReadResourceResult, McpError>

resources/read with a caller-supplied per-request timeout (the SHORT management bound, RFC 0016 §10) instead of the default ~60s. The reactor thread’s notify-then-read (read_current) blocks on this; a slow-but-alive resource server must not outrun the liveness heartbeat. A timeout surfaces as McpError::Timeout; the level-triggered reactor treats a timed-out read exactly like any read failure (act on empty / skip), so a transient slow read is recovered on the next updated notification or re-read.

pub fn subscribe(&self, uri: &str) -> Result<(), McpError>

resources/subscribe — gated on the server advertising it (RFC 0004).

pub fn subscribe_within( &self, uri: &str, _timeout: Duration, ) -> Result<(), McpError>

Self::subscribe with a caller-supplied timeout (the SHORT management bound, RFC 0016 §10) — for the reactor-thread reload re-handshake, where a slow-but-alive server arming a subscription must not block the reactor.

pub fn unsubscribe(&self, uri: &str) -> Result<(), McpError>

pub fn unsubscribe_within( &self, uri: &str, _timeout: Duration, ) -> Result<(), McpError>

Self::unsubscribe with a caller-supplied timeout (the SHORT management bound, RFC 0016 §10) — for the reactor-thread reload reconcile + the drain unsubscribe, both best-effort: a slow server here must not block the reactor or the drain past the liveness window / drain budget.

pub fn drain_notifications(&self) -> Vec<Notification>

Drain any notifications queued since the last drain (e.g. notifications/resources/updated). The reactive router (triggers/mode.rs) drains these between runs to drive re-reactions.

Trait Implementations

impl Drop for McpClient

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl McpCall for McpClient

fn call( &self, tool: &str, args: Value, meta: Value, timeout: Duration, ) -> Result<CallToolResult, String>

fn server_name(&self) -> String

impl SkillServer for McpClient

fn server_name(&self) -> String

fn supports_prompts(&self) -> bool

fn supports_resources(&self) -> bool

fn list_prompts(&self) -> Result<Vec<Prompt>, String>

fn get_prompt( &self, name: &str, arguments: Option<Value>, ) -> Result<Vec<Value>, String>

fn list_resources(&self) -> Result<Vec<Resource>, String>

fn read_resource(&self, uri: &str) -> Result<String, String>