Skip to main content

Crate mcp_guest

Crate mcp_guest 

Source
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::*;

Modules§

connect
error
handler
protocol
runtime
session
transport