Expand description
§mcp-guest
Async Rust client for Model Context Protocol servers, with tool discovery,
invocation, and result handling over stdio or HTTP. Uses Tokio; the protocol
types come from mcp-wire.
§Installation
Requires Rust 1.99 or newer.
[dependencies]
mcp-guest = "0.17.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }The default stdio feature connects to local server processes. Enable http
for remote servers, or use default-features = false, features = ["http"] for
HTTP-only clients.
HTTPS needs a rustls crypto provider, and the crate forces none: enable
tls-aws-lc or tls-ring (each implies http), or rely on a provider your
application already compiles into rama and installs as rustls’ process
default. Applications that standardised on one provider build only that one.
From the workspace root, just qa-tls ring and just qa-tls aws-lc validate
the two backends independently, including a dependency-graph guard against
compiling both providers. AWS-LC validation requires CMake; the default
application QA path does not.
mcp-guest = { version = "0.14.0", default-features = false, features = ["tls-aws-lc"] }let session = mcp_guest::stdio("my-mcp-server", &[]).connect().await?;
for tool in session.list_tools().await? {
println!("{}", tool.name);
}
session.disconnect().await?;§Sessions
With the http feature enabled, connect to a remote MCP server:
let session = mcp_guest::http("https://example.test/mcp")
.connect()
.await?;
session.disconnect().await?;An McpSession owns its runtime task and transport. Calling disconnect() is
idempotent: it first requests graceful shutdown, then force-closes the transport
and aborts the runtime if either exceeds its deadline. Stdio transports kill and
reap child processes during forced shutdown, so a configuration refresh cannot
leave superseded MCP server generations running.
Use .shutdown_timeout(duration) on the stdio connection builder to bound transport
shutdown for a server with a known termination budget.
§Telemetry
Requests emit mcp.guest.request spans through the application’s existing
tracing subscriber. They include the RPC method and completion status, never
parameters, response bodies, or error text. Request context follows queued
transport sends; no subscriber or OTLP exporter is installed by this library.
Cross-process trace-context propagation is not provided by these local spans.
§MCP Apps (ui://)
mcp-host 0.6 MCP Apps views use ui:// resource URIs and the MIME type
text/html;profile=mcp-app. ToolInfo::ui() parses tool _meta.ui links and
model/app visibility. list_ui_resources(), read_ui_resource(uri), and
read_tool_ui(&tool) discover and read views through the same MCP session.
Tool-linked views do not have to appear in resources/list.
let session = mcp_guest::stdio("my-mcp-server", &[]).connect().await?;
// Cache listing metadata for views that omit contents-level `_meta.ui`.
session.list_ui_resources().await?;
for tool in session.list_tools().await? {
if let Some(view) = session.read_tool_ui(&tool).await? {
let html = view.html()?; // Text or base64-encoded UTF-8 HTML.
// Pass html and view.ui to your sandboxed renderer.
// Original contents-level metadata remains in view.contents.
let _ = html;
}
}
session.disconnect().await?;Content-level _meta.ui replaces cached listing metadata, rather than merging
permissions. CSP origins are validated; missing policy means no allowed
external origins or browser permissions. Malformed metadata is an error.
The client does not render HTML, implement the iframe bridge, or grant
permissions. Only applications that provide a sandboxed MCP Apps renderer
should call .enable_mcp_apps() on either connection builder (or
ClientCapabilities::with_mcp_apps()). This advertises
capabilities.extensions["io.modelcontextprotocol/ui"].mimeTypes during
initialization. Apps support is off by default; raw server declarations alone
never enable it. Once enabled, hosts may expose app-only tools: embedding
applications must use ToolUi::is_visible_to(UiVisibility::Model) when building
the model’s tool catalog.
§Error classification
GuestError exposes is_retryable(), is_timeout(), and retry_after() as
inherent methods.
§License
BSD-3-Clause.
Re-exports§
pub use connect::HttpBuilder;pub use connect::StdioBuilder;pub use connect::http;pub use connect::stdio;pub use error::GuestError;pub use handler::ClientHandler;pub use handler::ClientHandlerFuture;pub use handler::ClientHandlerResultFuture;pub use handler::NoopClientHandler;pub use session::McpSession;pub use session::WeakMcpSession;pub use protocol::*;