fastmcp-client 0.9.0

Protocol status (2026-08-27): MCP 2026-07-28 support is under implementation and remains unverified. The root compatibility PROTOCOL_VERSION is 2024-11-05; the modern facade's modern::PROTOCOL_VERSION is 2026-07-28. Source presence, examples, and historical parity rows are not conformance or release evidence. Versions through 0.9.0 have been published, but publication and source edits alone do not prove historical workflow identities, queued runs, or credentials inert; provider-side release-safety evidence is still required.

Current qualification boundaries

• Wire cancellation is only partially qualified: on Unix, the primary stdio path keeps receiving while bounded modern requests run in independent request-owned children, so it can route cancellation during handler execution. Response and notification commits remain serialized at the output writer, while exact MCP 2024-11-05 traffic remains serialized through its lifecycle worker. Non-Unix stdio and custom/SSE/WebSocket entry points retain sequential or blocking boundaries. A non-cooperative handler can still exceed the bounded process-exit drain, so end-to-end quiescence and reliable awaitCleanup semantics remain unverified.
• Bidirectional calls are not qualified: the Unix stdio receive pump can route sampling, elicitation, and roots responses while exact-2024 lifecycle work or modern request children are active. Non-Unix stdio and custom/SSE/WebSocket paths reject or lack that split routing. Public HTTP has its own dual-era request and response routing, but end-to-end bidirectional lifecycle/cancellation evidence is incomplete.
• Response caching is conservatively partitioned: eligible production requests are keyed by committed authentication facts plus opaque session identity and revision. Uncommitted authentication, local-only state views, allocation failure, or state mutation during a request cause cache admission to fail closed rather than sharing an entry.
• Authentication admission is incomplete: native HTTP accepts credentials only from Authorization; recognized body/meta and query credential fields are rejected before the provider or application runs. Other adapters retain a stripped legacy JSON-RPC credential fallback. Complete authorization, lease/revocation, and OAuth challenge qualification remain open.
• Legacy Tasks RPC stays dead: tasks/list and tasks/submit return JSON-RPC MethodNotFound. Official MCP 2026-07-28 methods tasks/get, tasks/update, and tasks/cancel are served by default (process-local in-memory store). Call ServerBuilder::final_tasks to supply an application-owned store. Creating new tasks still requires the application to run a caller-owned task supervisor in its own Cx region. The historical with_task_manager path does not install the official methods.
• Authenticated local Tasks retain their caller: task creation atomically stores a private principal binding. Request get/update/cancel and Tasks subscriptions enforce that binding; a refreshed credential for the same verified owner can continue the task. Custom stores must implement atomic authenticated creation and preserve the binding in every snapshot. Context-free runtime and subscription APIs are trusted embedding controls. Anonymous client isolation, proxy Tasks ownership, durable authorization, grant revalidation, and revocation remain unqualified.
• OAuth/OIDC are unpromoted source surfaces: their public building blocks remain available for development, but production security/profile conformance is unverified and no production-support claim is made for them.
• CLI inspection is bounded diagnostics, not conformance evidence: with default features in a current source checkout, fastmcp inspect --protocol-policy reports the selected auto, modern-only, or legacy-only era. A selected modern session requires valid _meta.io.modelcontextprotocol/serverInfo metadata and retains the open discovery capability shape (including completions and extensions) subject to output bounds and credential/control-text sanitization; a selected legacy session renders only the exact legacy capability shape. A --no-default-features build supports modern-only only. This does not qualify either protocol era as aggregate conformance or production readiness.
• Subprocess cleanup is explicit and platform-bounded: Client::close(&mut self) returns cleanup failures. The opt-in owned-group mode used by fastmcp test is Unix-only and fails before spawn elsewhere. Its --protocol-policy option binds both client negotiation and the launched FastMCP server profile. It uses a live anchor plus an owner-death channel, but cannot contain descendants that change group/session, withstand a competing global child reaper, or close a control descriptor copied by a host-side fork. Drop is best effort.

# Current published package; publication is not aggregate conformance evidence
cargo add fastmcp-rust@0.9.0

# Or use the git dependency for bleeding-edge changes
cargo add fastmcp-rust --git https://github.com/Dicklesworthstone/fastmcp_rust

TL;DR

The Problem

MCP server implementations need to solve several recurring problems:

• Handler schemas and JSON-RPC dispatch
• Cooperative cancellation and request budgets
• Ownership of concurrent child work
• Transport framing and session lifecycle

The Solution

FastMCP Rust is an MCP framework with asupersync capability contexts, attribute macros, and explicit cancellation/budget surfaces:

use asupersync::runtime::{RuntimeBuilder, reactor::create_reactor};
use fastmcp_rust::{modern::ServerBuilder, prelude::*};

#[tool]
async fn greet(ctx: &McpContext, name: String) -> McpResult<String> {
    ctx.checkpoint()?;  // Cancellation point
    Ok(format!("Hello, {name}!"))
}

fn main() {
    let runtime = RuntimeBuilder::current_thread()
        .with_reactor(create_reactor().expect("create I/O reactor"))
        .blocking_threads(0, 16)
        .build()
        .expect("create application runtime");
    runtime.block_on(async {
        let cx = Cx::current().expect("application context");
        ServerBuilder::new("my-server", "1.0.0")
            // Attribute macros generate PascalCase handler values.
            .tool(Greet)
            .build()
            .run_stdio_with_cx(&cx)
            .await
    });
}

The application creates the runtime once and supplies its context. Stdio needs a blocking pool for its receive pump; FastMCP does not create a runtime at this entry point. See Quick Start below for the dependency declarations.

Why FastMCP Rust?

AGENTS.md

This project includes an AGENTS.md file with guidelines for AI coding agents. Key points:

• Porting methodology: Extract spec from legacy → implement from spec → never translate line-by-line
• Runtime: Uses asupersync exclusively; Tokio and Tokio-based adapters are unsupported
• Unsafe code: Forbidden (#![forbid(unsafe_code)])
• Toolchain: Rust 2024 edition; pinned nightly-2026-08-25 / rustc 1.100.0-nightly (rust-version = "1.100")
• MCP 2026-07-28 support is under implementation and remains unverified.
• Aggregate MCP 2026-07-28 support is not claimed by FND-01.
• The root compatibility PROTOCOL_VERSION is 2024-11-05; the modern facade's modern::PROTOCOL_VERSION is 2026-07-28. Neither is proof of negotiated 2026-07-28 support.

Quick Example

use asupersync::runtime::{RuntimeBuilder, reactor::create_reactor};
use fastmcp_rust::{modern::ServerBuilder, prelude::*};

// Define a tool with automatic JSON schema generation
#[tool(description = "Calculate the sum of two numbers")]
async fn add(ctx: &McpContext, a: i64, b: i64) -> McpResult<String> {
    ctx.checkpoint()?;  // Check the local cancellation token and budget
    Ok((a + b).to_string())
}

// Define an in-memory resource. Potentially blocking filesystem work is not
// performed inline on the dispatch worker.
#[resource(uri = "config://settings", description = "Application config")]
fn config(ctx: &McpContext) -> McpResult<String> {
    ctx.checkpoint()?;
    Ok(r#"{"theme":"dark"}"#.to_owned())
}

// Define a prompt template
#[prompt(description = "Generate a greeting message")]
async fn greeting(ctx: &McpContext, name: String) -> McpResult<Vec<PromptMessage>> {
    ctx.checkpoint()?;
    Ok(vec![PromptMessage {
        role: Role::User,
        content: Content::text(format!("Please greet {name} warmly.")),
    }])
}

fn main() {
    let runtime = RuntimeBuilder::current_thread()
        .with_reactor(create_reactor().expect("create I/O reactor"))
        .blocking_threads(0, 16)
        .build()
        .expect("create application runtime");
    runtime.block_on(async {
        let cx = Cx::current().expect("application context");
        ServerBuilder::new("example-server", "1.0.0")
            .tool(Add)
            .resource(ConfigResource)
            .prompt(GreetingPrompt)
            .request_timeout(30)  // 30-second budget per request
            .build()
            .run_stdio_with_cx(&cx)
            .await
    });
}

Run it:

# echo_server is a shipped binary target of the facade crate, not an example
cargo run -p fastmcp-rust --bin echo_server

Design Philosophy

1. Explicit Cooperative Cancellation

Handlers should check cancellation at natural suspension or iteration boundaries. FastMCP exposes cooperative checkpoints. These local context semantics do not, by themselves, make cancellation interruptible over a live connection; see the qualification boundaries above.

#[tool]
async fn process_items(
    ctx: &McpContext,
    items: Vec<String>,
) -> McpResult<Vec<Content>> {
    let mut results = vec![];
    for item in items {
        ctx.checkpoint()?;  // Allow graceful cancellation between items
        results.push(Content::text(process(item).await?));
    }
    Ok(results)
}

2. Budgets, Not Timeouts

Timeouts are "we gave up." Budgets are "you have X resources." The Budget type represents deadline, poll-quota, and cost-quota dimensions:

// Called from the application's runtime with its context.
async fn serve(cx: &Cx) -> ! {
    ServerBuilder::new("server", "1.0.0")
        .request_timeout(30) // 30-second server-owned request ceiling
        .tool(MyTool)
        .build()
        .run_stdio_with_cx(cx)
        .await
}

// Handler can check remaining budget
#[tool]
async fn my_tool(ctx: &McpContext) -> McpResult<String> {
    ctx.checkpoint()?;
    // ... work ...
    Ok("work completed".to_string())
}

3. Four-Valued Outcomes

Result<T, E> has no distinct cancellation or panic variants. FastMCP's asynchronous handler boundary uses Outcome<T, E>:

enum Outcome<T, E> {
    Ok(T),                    // Success
    Err(E),                   // Expected failure
    Cancelled(CancelReason),  // External interruption
    Panicked(PanicPayload),   // Internal failure
}

4. Capability-oriented handlers

Request authority flows through McpContext; application dependencies should likewise be passed explicitly instead of hidden in globals:

// BAD: Global state access
async fn bad_tool() {
    let db = GLOBAL_DB.lock().await;  // Hidden dependency
}

// GOOD: Explicit capability
async fn good_tool(ctx: &McpContext, db: &DbHandle) {
    db.query(ctx.cx(), "SELECT ...").await;  // Explicit
}

5. Owned Concurrent Futures

Concurrent child futures remain owned by the request handler and are polled together by context combinators:

use std::future::Future;
use std::pin::Pin;

#[tool]
async fn parallel_fetch(
    ctx: &McpContext,
    urls: Vec<String>,
) -> McpResult<Vec<Content>> {
    type FetchFuture = Pin<Box<dyn Future<Output = McpResult<String>> + Send>>;

    let futures: Vec<FetchFuture> = urls
        .into_iter()
        .map(|url| Box::pin(fetch(url)) as FetchFuture)
        .collect();

    let results = ctx.join_all(futures).await?;
    results
        .into_iter()
        .map(|result| result.map(Content::text))
        .collect()
}

Design Positioning

These are FastMCP Rust design surfaces, not benchmark results or an MCP 2026-07-28 conformance certificate. Competing projects change independently and should be evaluated from their current documentation rather than a static comparison table.

Installation

From crates.io (current 0.9.0 package)

The 0.9.0 package was published on 2026-09-11. Publication does not establish aggregate MCP 2026-07-28 conformance, production readiness, or qualification of every in-tree feature.

[dependencies]
fastmcp-rust = "0.9.0"

As a Git Dependency

[dependencies]
fastmcp-rust = { git = "https://github.com/Dicklesworthstone/fastmcp_rust" }
asupersync = "=0.4.10"

From Source

git clone https://github.com/Dicklesworthstone/fastmcp_rust.git
cd fastmcp_rust
cargo build --release

CLI binaries (GitHub Releases)

The latest published release, v0.9.0, provides prebuilt fastmcp binaries on GitHub Releases. The fastmcp-cli source package is also available from crates.io for Cargo-based installation. Its archives use fastmcp-<os>-<arch> names (.tar.xz on Unix, .zip on Windows). Linux and macOS provide x86_64 and aarch64 archives (fastmcp-linux-x86_64, fastmcp-linux-aarch64, fastmcp-darwin-x86_64, fastmcp-darwin-aarch64); Windows provides fastmcp-windows-x86_64 (MSVC). There are no amd64/arm64 alias names. Every archive has a .sha256 sibling and the release carries a SHA256SUMS file. The checked-in release workflow is currently a quarantined verification surface and does not publish new GitHub Releases.

# Example: macOS Apple Silicon
curl -fsSL -O https://github.com/Dicklesworthstone/fastmcp_rust/releases/latest/download/fastmcp-darwin-aarch64.tar.xz
tar -xJf fastmcp-darwin-aarch64.tar.xz
./fastmcp --version

CLI via Cargo (optional)

cargo install fastmcp-cli --version 0.9.0

Client request deadlines (current source tree)

Ordinary client requests use separate idle and absolute response-wait deadlines. Both begin after the request send commits. The idle deadline defaults to 30 seconds; the non-resettable absolute deadline defaults to 120 seconds. Serialization, sending, and teardown are outside these timers. Unix subprocess sends have a separate two-second bound covering writer-lock acquisition and the native pipe commit. These commits remain synchronous; non-Unix sends retain blocking-I/O limits. Only a valid matching progress notification on a request that actually supplied a progress token can reset idle.

On Unix, eager ClientBuilder::connect_stdio_with_cx initialization also yields between bounded receive turns, including partial responses and Auto negotiation. A fallback child starts only after the disposable modern child has been cleaned up. With auto_initialize(true), async requests and Client::ensure_initialized_with_cx also yield during the first handshake. Dropping that future preserves the handshake, partial response and original deadline; the next async or synchronous call resumes it without another send. Explicit cancellation after the handshake starts fails the connection. Synchronous constructors and synchronous first use retain their blocking boundaries; subprocess creation and write commits remain synchronous.

use std::time::Duration;

use fastmcp_rust::prelude::{Client, ClientBuilder, Cx, McpResult, RequestTimeoutPolicy};

async fn connect(cx: &Cx) -> McpResult<Client> {
    let policy = RequestTimeoutPolicy::new(
        Duration::from_secs(20),
        Duration::from_secs(90),
    )?;
    ClientBuilder::new()
        .request_timeout_policy(policy)
        .connect_stdio_with_cx("my-mcp-server", &[], cx)
        .await
}

A live modern subscriptions/listen can stay open on the same stdio Client while other requests complete. Call Client::open_subscriptions_listener and then Client::next_subscription_event to drain acknowledgement, catalog, and resource-update events without collecting the stream to terminal. On Unix, open_subscriptions_listener_with_cx and next_subscription_event_with_cx yield during initialization and between bounded receive turns. Tasks offer the corresponding open_final_task_subscription_listener_with_cx and next_final_task_subscription_event_with_cx APIs. Dropping an event future preserves the stream and partial frame for resumption; explicit cancellation retires only that listener, leaving sibling requests usable. Cancellation write failures retain the listener and its error. Writes remain synchronous. listen_subscriptions_typed remains the collect-to-terminal adapter. The same incremental pattern exists on HTTP (HttpClient::start_subscriptions_listener), modern WebSocket (WebSocketClient::open_subscriptions_listener), and ProxyClient::start_catalog_listener for stdio and modern HTTP upstreams. Proxy catalog and Tasks listener startup and event methods are async and take the caller's &Cx. HTTP opening yields while awaiting headers; cancelling or dropping that opening closes its socket and releases the route for another attempt. Dropping an event future preserves the installed listener for resumption. Stdio startup and bounded receive turns retain their synchronous I/O limits. ProxyUpstreamBindingRegistry::connect_http_with_protocol_plan and connect_stdio_with_protocol_plan are async and take the caller's &Cx first. HTTP negotiation and exact-2024 initialization await that runtime; Unix stdio initialization uses the client's yielding receive path. Interrupted openings leave the registry cache unchanged, allowing a fresh attempt. Keep the caller runtime alive while using a cached legacy HTTP/SSE connection. Use ProxyClient::catalog_typed_with_cx or catalog_with_cx to fetch HTTP or stdio catalogs on that runtime, including every page and its modern cache hints. These methods release the route lock while awaiting HTTP I/O or between bounded stdio receive turns and reject cursor cycles without returning a partial catalog. Stdio writes and individual receive turns retain their synchronous I/O limits. Backends without an upstream binding retain their synchronous catalog implementation.

Exact-2024 resource subscribe/unsubscribe hooks also have awaited variants: ResourceHandler::on_subscribe_async and on_unsubscribe_async. The live dispatcher and mounted resources forward these hooks on the caller runtime. Native proxies release the route lock during HTTP/SSE waits and between bounded stdio receive turns. Failed or interrupted proxy requests preserve local URI rewrites, and failed synchronous hooks roll back the session's subscription membership. Remote effects already acknowledged upstream cannot be rolled back by these guarantees.

HTTP and WebSocket clients also expose typed list_tools/call_tool/ read_resource/get_prompt verbs so callers do not have to decode a raw core result for ordinary catalog and invocation traffic. HTTP and WebSocket list_tools_with_cancellation/call_tool_with_cancellation/ read_resource_with_cancellation/get_prompt_with_cancellation honor a caller-owned cancellation domain for those ordinary verbs. Exact MCP 2024-11-05 HTTP+SSE clients use Client::sse_with_cx when the GET event stream and POST message endpoints are already known.

On Unix, Client::call_tool_with_cx, read_resource_with_cx, and get_prompt_with_cx follow installed async reverse handlers when a modern peer requests input. After initialization, all rounds and handler waits share one absolute deadline; cancellation drops pending handler work and preserves the connection. Deferred discovery keeps its separate initialization deadline and connection-ending cancellation rules. Each retry carries the original arguments and only the latest continuation state. Without installed handlers, the input-required result is returned to the caller.

Installed modern MRTR callbacks also remain cancellable while pending in HTTP and WebSocket clients, including callbacks that never wake themselves. Dropping or interrupting a callback cancels its local token and prevents a continuation; callback panics become redacted errors. These checks run between callback polls and cannot preempt synchronous work or undo external effects inside user code.

With the tasks feature on Unix, Client::call_tool_final_outcome_with_cx creates tasks without blocking the runtime while waiting for the peer. It returns the typed complete, task, or input-required outcome. A returned task ID can be used with get_task_final_with_cx and cancel_task_final_with_cx on the same client. An already-admitted valid task result survives caller cancellation; other results remain cancellation-first. Input-required results are returned without automatic continuation. Pipe writes remain synchronous.

The published 0.9.0 CLI includes these flags. From a current source checkout, run the CLI through the workspace to configure the two limits independently:

cargo run -p fastmcp-cli -- test --protocol-policy auto --idle-timeout 30 --absolute-timeout 120 my-mcp-server

The current fastmcp test subprocess runner is Unix-only because success includes verified owned-process-group cleanup. Library callers should likewise call client.close() and handle its McpResult; dropping a client is only a best-effort safety net. The group anchor protects its numeric PGID while it is live and closes an owner-death channel when the host exits, but this is not portable process-tree containment or a substitute for Windows Job Objects.

Requirements:

• Rust nightly-2026-08-25 (see rust-toolchain.toml) for Edition 2024. The last FND-01 evidence snapshot still records nightly-2026-07-11 until that harness is re-attested.

Tasks commands (current source tree, optional)

Build the CLI with --features tasks to expose tasks get, watch, update, and cancel. These commands require modern MCP and bilateral io.modelcontextprotocol/tasks support. The pinned extension is experimental; this source implementation remains provisional. The published 0.9.0 binary does not include these commands.

cargo run -p fastmcp-cli --features tasks -- tasks get TASK_ID --http-url http://127.0.0.1:8000/mcp --json
cargo run -p fastmcp-cli --features tasks -- tasks watch TASK_ID --http-url http://127.0.0.1:8000/mcp --timeout 60 --max-events 100 --json
cargo run -p fastmcp-cli --features tasks -- tasks update TASK_ID --http-url http://127.0.0.1:8000/mcp --input-file responses.json --json
cargo run -p fastmcp-cli --features tasks -- tasks cancel TASK_ID --http-url http://127.0.0.1:8000/mcp --json

The input file contains the inputResponses map itself, for example {"roots":{"roots":[]}} when the task's outstanding input key is roots and its method is roots/list. Files are limited to 1 MiB. Updates use the current task's input request types. Update and cancellation success mean acknowledgement; use get or watch to observe subsequent task state.

Watch emits an initial snapshot, subscription acknowledgement, live task updates, and an exit reason. It does not reconnect or promise replay across disconnects. --timeout defaults to 30 seconds; timeout is a failed command, while reaching --max-events ends the watch successfully without cancelling the task. JSON mode emits one document per event; human output bounds and sanitizes fields and redacts recognizable credentials.

Use --server EXECUTABLE and repeat --server-arg ARGUMENT for stdio. Each command starts a fresh process, so previously issued task IDs require a store retained outside the prior process. For authenticated HTTPS, Tasks commands and inspect accept --bearer-token-file PATH:

cargo run -p fastmcp-cli --features tasks,native-tls-roots -- tasks get TASK_ID --http-url https://mcp.example.com/mcp --bearer-token-file token.txt --json

The file must contain a UTF-8 token of at most 16 KiB, including an optional trailing LF or CRLF. Do not include a Bearer prefix or other whitespace or control characters. The CLI reads a regular file once per invocation; callers own token acquisition and refresh. Credentials require HTTPS and a modern or auto protocol policy. Core-only builds omit Tasks from help and explain the required feature when a Tasks command is attempted.

Authenticated HTTP clients (current source tree)

The SDK accepts a caller-acquired bearer credential bound to one exact HTTPS endpoint. For example, with a caller-owned cx and an existing token:

use fastmcp_rust::{BoundBearerCredential, CanonicalHttpUrl, modern};

let endpoint = CanonicalHttpUrl::parse("https://mcp.example.com/mcp")?;
let credential = BoundBearerCredential::bind(endpoint.clone(), token)?;
let client = modern::ClientBuilder::new()
    .http_bearer_credential(credential)
    .connect_http_with_cx(endpoint, cx)
    .await?;

The same credential binding covers discovery, later request/subscription POSTs, and reverse-response POSTs. It never attaches to cleartext HTTP, a different path or query, or a redirect target. An authenticated Auto client refuses legacy fallback. Applications own token acquisition and refresh; create a new client when the credential changes. The CLI's --bearer-token-file uses this same binding.

The bounded JSON/SSE readers withhold JSON-RPC errors that reflect the exact credential into their message or data, returning a typed diagnostic instead. Successful application results and the raw native-stream API remain unmodified.

HTTPS uses the transport's bundled WebPKI roots by default. Enable native-tls-roots on fastmcp-rust, fastmcp-client, or fastmcp-cli for the platform trust store. That profile also honors the native certificate provider's SSL_CERT_FILE and SSL_CERT_DIR overrides; these select the trust source, and do not disable certificate or hostname verification.

Quick Start

1. Create a New Project

cargo new my-mcp-server
cd my-mcp-server

2. Add FastMCP

# Cargo.toml
[dependencies]
fastmcp-rust = { git = "https://github.com/Dicklesworthstone/fastmcp_rust" }
asupersync = "=0.4.10"

3. Write Your Server

// src/main.rs
use asupersync::runtime::{RuntimeBuilder, reactor::create_reactor};
use fastmcp_rust::{modern::ServerBuilder, prelude::*};

#[tool(description = "Echo the input message")]
async fn echo(ctx: &McpContext, message: String) -> McpResult<String> {
    ctx.checkpoint()?;
    Ok(message)
}

fn main() {
    let runtime = RuntimeBuilder::current_thread()
        .with_reactor(create_reactor().expect("create I/O reactor"))
        .blocking_threads(0, 16)
        .build()
        .expect("create application runtime");
    runtime.block_on(async {
        let cx = Cx::current().expect("application context");
        ServerBuilder::new("echo-server", "1.0.0")
            .tool(Echo)
            .instructions("A simple echo server for testing")
            .build()
            .run_stdio_with_cx(&cx)
            .await
    });
}

4. Run

cargo run

5. Test with MCP Inspector

npx @modelcontextprotocol/inspector cargo run

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ JSON-RPC over stdio
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      StdioTransport                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │   Codec     │───▶│   recv()    │───▶│   send()    │         │
│  │  (NDJSON)   │    │             │    │             │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Server                                  │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │   Session   │    │   Router    │    │   Budget    │         │
│  │  (state)    │    │ (dispatch)  │    │ (timeout)   │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                     McpContext                              ││
│  │  ┌─────┐  ┌──────────┐  ┌────────┐  ┌──────┐              ││
│  │  │ Cx  │  │checkpoint│  │ budget │  │masked│              ││
│  │  └─────┘  └──────────┘  └────────┘  └──────┘              ││
│  └─────────────────────────────────────────────────────────────┘│
│                              │                                  │
│                              ▼                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ ToolHandler  │  │ResourceHandler│ │PromptHandler │         │
│  │  call_async  │  │  read_async  │  │  get_async   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       asupersync                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │ Runtime │  │  Scope  │  │ Budget  │  │ Outcome │           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
└─────────────────────────────────────────────────────────────────┘

Crate Structure

FastMCP is organized as a workspace with focused crates:

fastmcp_rust/
├── crates/
│   ├── fastmcp/           # Facade crate (published as fastmcp-rust)
│   ├── fastmcp-core/      # McpContext, errors, runtime helpers
│   ├── fastmcp-protocol/  # MCP types, JSON-RPC messages
│   ├── fastmcp-transport/ # Transport implementations (stdio, SSE, WebSocket, HTTP, memory)
│   ├── fastmcp-server/    # Server builder, router, handlers
│   ├── fastmcp-client/    # Client implementation
│   ├── fastmcp-macros/    # Proc-macro crate, published as fastmcp-derive
│   ├── fastmcp-console/   # Console rendering and statistics
│   └── fastmcp-cli/       # fastmcp command-line interface

Handler Traits

The signatures below are abridged; asynchronous trait methods return four-valued McpOutcome values, not ordinary McpResult values.

ToolHandler

pub trait ToolHandler: Send + Sync {
    fn definition(&self) -> Tool;
    fn call(
        &self,
        ctx: &McpContext,
        arguments: serde_json::Value,
    ) -> McpResult<Vec<Content>>;

    // Override for true async (default delegates to call())
    fn call_async<'a>(&'a self, ctx: &'a McpContext, arguments: serde_json::Value)
        -> std::pin::Pin<Box<dyn std::future::Future<Output = McpOutcome<Vec<Content>>> + Send + 'a>>;
}

ResourceHandler

pub trait ResourceHandler: Send + Sync {
    fn definition(&self) -> Resource;
    fn read(&self, ctx: &McpContext) -> McpResult<Vec<ResourceContent>>;

    // Override for true async
    fn read_async<'a>(&'a self, ctx: &'a McpContext)
        -> std::pin::Pin<Box<dyn std::future::Future<Output = McpOutcome<Vec<ResourceContent>>> + Send + 'a>>;
}

PromptHandler

pub trait PromptHandler: Send + Sync {
    fn definition(&self) -> Prompt;
    fn get(&self, ctx: &McpContext, arguments: std::collections::HashMap<String, String>)
        -> McpResult<Vec<PromptMessage>>;

    // Override for true async
    fn get_async<'a>(
        &'a self,
        ctx: &'a McpContext,
        arguments: std::collections::HashMap<String, String>,
    )
        -> std::pin::Pin<Box<dyn std::future::Future<Output = McpOutcome<Vec<PromptMessage>>> + Send + 'a>>;
}

Troubleshooting

Critical Section Example

use std::sync::atomic::{AtomicU64, Ordering};

// A handler that owns `committed` can call this helper after validation.
fn commit_revision(
    ctx: &McpContext,
    revision: u64,
    committed: &AtomicU64,
) -> McpResult<()> {
    // Mask only a small, non-blocking atomic commit. Masking does not make
    // synchronous filesystem or device I/O bounded or cancel-safe.
    ctx.masked(|| committed.store(revision, Ordering::Release))
        .map_err(|error| McpError::internal_error(error.to_string()))?;
    Ok(())
}

Limitations

FAQ

Q: Why is Tokio unsupported?

A: FastMCP Rust is built around asupersync capability contexts, budgets, and cooperative-cancellation surfaces. Tokio and Tokio-based adapters are outside the supported runtime model.

Q: Can I use this with Claude Desktop?

A: Stdio integration exists, but compatibility must be checked against the client: the root compatibility PROTOCOL_VERSION is 2024-11-05, the modern facade's modern::PROTOCOL_VERSION is 2026-07-28, and MCP 2026-07-28 support is not yet verified.

Q: How do I add authentication?

A: Install an AuthProvider through the server builder. Native HTTP uses the Authorization header and rejects recognized credentials in JSON-RPC params, their _meta/headers containers, and query parameters with a fixed migration diagnostic. Static tokens remain a non-OAuth deployment mode; applications own TLS termination and token provisioning. Other transport adapters retain a stripped legacy JSON-RPC credential fallback. OAuth/OIDC production security, continuous authorization and profile conformance remain unverified.

Q: What's the performance overhead of checkpoints?

A: Checkpoints perform cancellation and budget checks. No project benchmark currently supports a universal per-call latency claim; measure them in the target workload if the cost matters.

Q: Can I use other async runtimes?

A: No. The current API and implementation require asupersync; other async runtimes are not supported.

Q: How do I test my handlers?

A: Construct McpContext from an asupersync testing context and a request ID:

use fastmcp_rust::{Cx, McpContext, McpResult, tool};

#[tool]
fn my_tool(ctx: &McpContext, input: String) -> McpResult<String> {
    ctx.checkpoint()?;
    Ok(input)
}

#[test]
fn test_my_tool() {
    let ctx = McpContext::new(Cx::for_testing(), 1);
    let result = my_tool(&ctx, "input".to_string());
    assert_eq!(result.unwrap(), "input");
}

About Contributions

Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

FastMCP Rust is distributed under the terms in LICENSE: the MIT License with the included OpenAI/Anthropic rider. Every workspace crate uses that file as its Cargo license-file. LICENSE-MIT is retained as a reference copy of the underlying MIT text; it is not an alternative license for this project.