fastmcp-protocol 0.14.0

MCP protocol types and JSON-RPC implementation
docs.rs failed to build fastmcp-protocol-0.14.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: fastmcp-protocol-0.13.0

Protocol status (2026-11-22): 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.14.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.

Measured official-conformance standing

Run it yourself with scripts/run_official_conformance.sh; it owns the suite pin and the result tally. Measurements use @modelcontextprotocol/conformance@0.2.0-alpha.10, --spec-version 2026-07-28 --suite all, server mode against the in-tree conformance_server adapter:

revision date scenarios checks SUCCESS FAILURE WARNING INFO
65d2247d 2026-11-20 40 115 112 0 2 1
1c2dc896 2026-10-12 40 115 112 0 2 1
e2a0ac5c 2026-10-12 40 115 110 0 4 1
99a3b4e8 2026-10-05 40 115 110 0 4 1
working tree (unanchored) 2026-10-04 40 115 110 0 4 1
6b54e023 2026-10-03 40 114 108 1 4 1
bba5a09f 2026-10-01 40 92 54 38 0 0

The latest 65d2247d re-measurement (2026-11-20, arm64 Darwin, pinned nightly-2026-08-25, conformance_server adapter blob a2d1f906889039b7d5935464b2fa934adc585630, binary sha256 c3b4385de40dc4d0...f2deb37ec, suite exit status: 0) reproduces the 112 SUCCESS / 0 FAILURE / 2 WARNING / 1 INFO standing across all 40 scenarios and 115 checks.

The 99a3b4e8 row is bound to identity rather than to a date, which the row above it is not: 98 commits and 388 lines across four server-mode source files (fastmcp-core/src/context.rs, fastmcp-protocol/src/server_discovery.rs, fastmcp-server/src/lib.rs, fastmcp/src/lib.rs) landed after the 2026-10-04 measurement, which under this project's own receipt rules invalidated it. The re-measurement reproduces it exactly, so the standing held across that drift — but that is now a measured fact rather than an assumption. Its bindings:

HEAD              99a3b4e8f0ebd56357f34953754ac6912df0597b
adapter blob      0b887aedeb0b7f6ad3ddceb5ea3cc3523bbab29b
adapter sha256    a66f0bee...e149b4   crates/fastmcp/examples/conformance_server.rs
binary sha256     74c18713...e54a1a   target/debug/conformance_server
toolchain         rustc 1.100.0-nightly (e7769602a 2026-08-24)
host              hz3 (x86_64 linux), direct ssh, RCH scheduler bypassed
build             cargo build --locked -p fastmcp-rust --features tasks
                  --bin conformance_server, rc 0, 32m24s

--baseline cannot currently pass, and that is a property of the gate, not of the server. The suite's own --expected-failures treats a scenario carrying a SHOULD-level WARNING as a scenario failure, so this run reported suite exit status: 1 and named server-stateless, input-required-result-missing-input-response and input-required-result-ignore-extra-params as "unexpected failures" while its own tally printed 110 passed, 0 failed. Anyone wiring --baseline into a gate today gets a permanent red. Resolving that means either listing those scenarios (an expected-failures edit, which scripts/conformance-expected-failures.yaml deliberately reserves to its owner) or gating on the tally instead; it is not resolved here.

These rows are not a ratio, and the denominator is not fixed. It rose 92 → 114 → 115 because a scenario that fails an early check never runs its later ones, so fixing one check can add checks to the run. The corollary is a trap: a regression that makes a scenario abort earlier shrinks the denominator and can push a percentage up. Compare the sets of failing check ids, which is what scripts/conformance-expected-failures.yaml records and what the suite's own --expected-failures gates on.

Client mode. The gate is the harness passing in both modes. 32 scenarios / 155 checks: SUCCESS=55, FAILURE=46, SKIPPED=2, WARNING=1, INFO=51. Re-measured 2026-11-20 at 65d2247d (adapter blob fcf1296f971c60ce778bfd63dc5cdd7dcd610b22, binary sha256 066a512dc2a2d92d...99170934ca, arm64 Darwin, pinned nightly-2026-08-25), reproducing the 2026-10-13 2b6c519e baseline (crates tree 6a57e7ca, adapter binary sha256 2d47186b24962718e3e9a01be48f746449823ecf..., host hz3, suite @modelcontextprotocol/conformance@0.2.0-alpha.10, client --suite all --spec-version 2026-07-28, build rc 0, suite rc 1) across all five counts:

This row previously read "most recent run" with no revision, date, host or toolchain, which made it unverifiable; the re-measurement reproduces all five counts exactly. Split it before quoting it, because the halves measure different things:

checks SUCCESS FAILURE
non-authorization 55 52 0
authorization 100 3 46
  • Non-authorization: no FAILURE-level check remains. http-custom-headers 18/18, http-invalid-tool-headers 11/11, http-standard-headers 9/9 (2 skipped), sep-2322-client-request-state 5/5, json-schema-ref-no-deref, request-metadata (1 SHOULD warning) and tools_call clean. SEP-2243 parameter-header mirroring is exercised end to end: designated parameters are sent as Mcp-Param-*, encoded where the value is header-unsafe, omitted when null, and never added for an undesignated parameter — and a tool whose x-mcp-header annotations are invalid is excluded rather than called.

  • Authorization: the adapter, not the library. conformance_client supplies no interactive OAuth driver, so these measure adapter completeness. It does ship a non-interactive authorization-code driver — examples/conformance_oauth.rs plus its managed submodule, compiled into the adapter as a module and wired at conformance_client.rs:376 — but that driver is inert unless FASTMCP_CONFORMANCE_OAUTH carries its configuration, and nothing in this repository sets it, including scripts/run_official_conformance.sh. So these checks measure the adapter with authorization switched off. No value of that variable can switch it on, though. Measured 2026-10-12 against the pinned suite: configure requires the resource member to equal the MCP endpoint and to use https (conformance_oauth.rs:306), and issuer and authorization_endpoint are required static pins rather than discovered values. The suite serves plain HTTP on an ephemeral loopback port and has no TLS capability at all — a census of its 472,891-byte bundle finds http://localhost:${this.port} and http://127.0.0.1:${e} against zero occurrences of createSecureServer, node:tls, or any cert/key material — and it stands up a fresh authorization server per scenario, across 25 auth/* client scenarios that deliberately vary the issuer (iss-wrong-issuer, metadata-issuer-mismatch, authorization-server-migration). So the driver refuses any configuration naming the suite's endpoint, on two independent grounds. Closing these needs more than an adapter profile, which is worth stating precisely because the cheap-sounding estimate is wrong. The HTTPS requirement is not one check in the conformance adapter: a census of crates/fastmcp-client/src, with cfg(test) modules excluded, finds 32 production HTTPS enforcement points across 24 files: 30 independent scheme() != "https", starts_with("https://"), or scheme().is("https") refusals in http_auth.rs, device/wire.rs, challenge.rs, private_key_jwt.rs, metadata_document.rs, dpop.rs, dpop/native/core/stream/task_subscription/watch/checkpoint.rs, driver.rs, redirect.rs, enterprise/identity.rs, enterprise/identity/sector.rs, enterprise/keys.rs, enterprise/oidc.rs, enterprise/policy.rs, http_client.rs, managed/client.rs, resume.rs, oauth.rs, revocation.rs, recovery.rs, repair.rs, http_executor.rs and parameter_headers.rs, plus the two central helpers validate_https and https_url in discovery.rs. Thirteen further call sites — in challenge.rs, step_up.rs, issuer.rs and registration.rs — inherit those helpers' refusal rather than repeating it, so they are not separate edits. (This row previously read "32 production HTTPS hard-gates across 19 files" and then named 18. Both figures were wrong when written rather than stale: the same instrument returns 22 across 17 both at the authoring commit aac6f67c and at HEAD, so the subject never moved. The corrected figure is smaller, i.e. the earlier row overstated the work.) Reaching the suite's ephemeral plain-HTTP loopback authorization server therefore means threading a loopback exemption through all of them, which is a change to the transport security posture of the whole client authorization subsystem, plus accepting a discovered issuer where OAuthDiscoveryPlan currently takes a caller-supplied TrustedOAuthIssuer allowlist. And the exemption is not spec-backed in the direction that matters: RFC 8252 §7.3 permits loopback http for the client's own redirect URI, which is not what blocks us, while OAuth 2.1 requires https for the authorization server's own endpoints — exactly the URLs these 32 enforcement points refuse. The pinned suite serves its authorization server over plain http as a harness convenience, not because the spec allows it. So permitting it would be a real relaxation beyond the spec, not a reviewed alignment with it, and it is a library decision rather than adapter plumbing. It is not taken here.

    But a reviewed loopback-HTTP exemption already exists in this library, and the conformance adapter already uses it. This row previously claimed "no loopback exemption anywhere", which is false. ReviewedToolHeaders::new_for_loopback_http (http_executor/parameter_headers.rs) is public and documented: it admits canonical IPv4/IPv6 loopback literals over plain http and deliberately refuses DNS names, localhost included, "because a name can be rebound and is therefore not proof of a loopback peer". Its doc states the threat model it accepts — "loopback provides neither peer authentication nor secrecy from other local processes" — and requires per-binding caller review. examples/conformance_client.rs branches on the endpoint scheme to call it, and resolves the harness's http://localhost:<port> to the loopback literal in the adapter, on the stated ground that "resolving the name is the HOST's decision to make, not the library's … the library's literal-only boundary stays intact". So the precedent, the threat model, and the host-versus-library trust split are all settled here already — for parameter headers. What is not settled, and is the actual decision, is whether the same split is acceptable for the authorization server's own endpoints, where these 32 points protect credential transport rather than header mirroring. That is a strictly stronger property, so the existing precedent narrows the question rather than answering it.

    A trap for whoever does take it. Gating the exemption behind a conformance-only feature or cfg would be the cheap version and is self-defeating as proof: the 46 passing checks would then measure a profile no user can build, so they would be evidence about a conformance-only code path rather than about shipped behaviour. Either the shipped validators take a beyond-spec loopback exemption as an explicit, reviewed decision, or these 46 stay closed and are reported as a deliberate boundary — which, given that OAuth 2.1 requires https for authorization-server endpoints, is a defensible place to land rather than a gap to apologise for. They are also not one problem. The pinned suite drives PKCE (code_challenge), authorization_code, dynamic register, and 401 WWW-Authenticate + resource_metadata discovery, all of which this client implements. None of the 46 is DPoP, which this row used to imply. The suite does carry DPoP client scenarios — auth/dpop and auth/dpop-nonce — but both are tagged [extension] rather than a dated spec version, so --spec-version 2026-07-28 filters them out: list --client reports 43 scenarios unfiltered and 32 at that version, and dpop/sep-1932 appear zero times anywhere in the run. So DPoP is not measured at this pin, and the 46 are entirely authorization-flow checks (protected-resource and authorization-server metadata, client registration, authorization and token requests, iss handling, scope derivation and step-up, the three token-endpoint auth methods, CIMD, pre-registration, offline access and AS migration). DPoP (RFC 9449) primitives now exist and compile, which was not true before 2026-10-12, and the surface is growing faster than this row can be rewritten: measured 2026-10-16 at 7bd44cd0, fastmcp_client::http_auth::dpop was 57 files, 24,095 lines, 151 public items and 311 in-module tests, plus 515 lines and 7 tests in fastmcp_protocol::dpop behind the jose feature — 24,610 lines in all; re-measured 2026-11-20, the three DPoP trees (fastmcp-client/src/http_auth/dpop, fastmcp-client/src/http_auth/oauth/dpop, and fastmcp-protocol/src/dpop.rs) span 78 files and 36,739 lines. The trajectory is the point rather than any one reading: 781 lines on 2026-10-12, 6,699 at a6559ff2, 10,541 at acc20148, and 24,095 at 7bd44cd0 two days after that — 30.8× in four days, with the in-workspace caller count zero at every reading. That is the module keeping its own promise, not a widening gap: it is caller-driven by design, so the consumer is the application. Treat the counts as a dated reading of a module under active construction, not a durable fact; the gate below deliberately does not pin them, because a check that reddens on ordinary growth is a check that gets switched off. It is reachable by facade users through pub use fastmcp_client::http_auth. It had been unwired rather than absent — the file was created by 2612a7d4, the pub mod dpop; that puts it in the build was added only by ac00c6ad, and the only mod dpop declaration in http_auth.rs is that one, so those lines had never been compiled until then. (They had never been formatted either; c65eced1 restored cargo fmt --check afterwards.) It has no in-workspace consumer, and that is its design rather than a gap — a correction to what this row said earlier today. The module documentation states that it "never promotes a DPoP token into the existing bearer-only OAuth driver" and "does not install automatic OAuth negotiation or HTTP retries", so the intended consumer is the application, not this SDK. See Sender-constrained credentials: DPoP under Authenticated HTTP clients for the caller-facing flow; the real gap was that nothing pointed a reader at it, which is now fixed. So readme_mechanical_claims.rs gates the zero in the opposite sense from the one this row first claimed: the check fails if the library ever starts driving DPoP itself, which is the promise the module makes and the thing worth protecting. The size and its growth rate are still worth recording: 781 lines on 2026-10-12 to 24,610 across two crates four days later. (An earlier version of this sentence ranked that against "http.rs is 14,734 lines and websocket.rs 6,828". That comparison was wrong and is withdrawn: it set a whole module against a whole module, while the unclaimed surface in those two is one adapter struct and one cfg(test) codec respectively. http.rs itself is heavily consumed — HttpResponse, HttpStatus, HttpRequest and HttpMethod alone account for 680 mentions in fastmcp-server/src — so its line count measures something else entirely.) Tracked as bd-iaqgd. Across every member src/ file outside the three DPoP module trees, the lowercase path spelling dpop occurs three times, and all three are the pub mod dpop; declarations that put the modules in the build (http_auth.rs:39, http_auth/oauth.rs:45, fastmcp-protocol/src/lib.rs:44); outside src/, integration test targets (crates/fastmcp-client/tests/dpop_task_recovery.rs and crates/fastmcp/tests/public_reexport_closure.rs) exercise the public DPoP API surface, while shipped library paths in src/ remain caller-driven rather than auto-wired. Case is the discriminator — Rust spells the path dpop while prose and wire values spell it DPoP. Beyond those three declarations, the automatic path still states "No automatic login/retry, DPoP, DCR, DNS pinning, or OIDC identity authentication is installed" (http_auth/discovery/challenge.rs), and the client-credentials path still rejects a sender-constrained token (token_type: "DPoP", or a cnf holding jkt) under the test machine_token_cannot_downgrade_sender_constraints_or_exchange_grants. So the five DPoP checks stay unreachable, but the estimate changed: it is now "drive an existing primitive from the adapter", not "implement DPoP" — and it is still behind the loopback-HTTP blocker above, since the adapter cannot address the suite's authorization server at all. The split across causes is now measured, and it is not a split: all 46 are the adapter-profile blocker and none is a missing library capability. The nine in-tree oauth_* test targets are gated on native-tls-roots; each one now carries a matching required-features stanza, so a default run excludes them and naming one explicitly makes cargo refuse. They are therefore not a vacuous pass — but they are also not evidence those flows work, because a default run does not execute them at all.

Client-mode conformance is measured; aggregate conformance is still not claimed, in either mode.

No server-mode FAILURE-level check remains, and two of the four SHOULD-level warnings are now gone. The two that cleared were sep-2575-server-sends-tools-list-changed-on-subscription and its prompts counterpart, which the adapter had declined on the stated grounds that "the server has no runtime catalog-mutation API". That was false: McpContext exposes disable_tool/enable_tool and the resource and prompt pairs, each publishing a catalog change, and the server already attached both the session state and the subscriptions/listen publisher. Serving the suite's two trigger fixtures through that API took no library change at all — only examples/conformance_server.rs, +93/-4. The e2a0ac5c and 1c2dc896 rows above are a measured before/after over an identical 99-check id set, with exactly those two statuses changing and nothing else moving, so the +2 is not a denominator shift.

The two remaining warnings are enumerated in that same file: both are the deliberate fail-closed choice about empty MRTR response maps that the suite would prefer we relax.

What this is not. It is a count of named checks at one revision, under one adapter, over HTTP. It is not aggregate MCP 2026-07-28 conformance, and it says nothing about the qualification boundaries below — several of which (OAuth/OIDC production profile, end-to-end quiescence, awaitCleanup) the suite does not exercise at all. The suite's default --suite active omits roughly half the scenarios, including every input-required one, so a measurement taken without --suite all is not comparable to these rows.

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. WebSocket connections use native asynchronous I/O for Auto, ModernOnly, and LegacyOnly, without a connection-wide blocking worker. Exact-2024 handlers remain serialized while reverse replies and cancellation continue to be received. Non-Unix stdio and custom/SSE entry points retain sequential or blocking boundaries, except that an unsplit custom transport runs subscriptions/listen off its receive loop and queues output produced while recv blocks until recv returns. 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 only partly qualified: the Unix stdio receive pump can route sampling, elicitation, and roots responses while exact-2024 lifecycle work or modern request children are active. The WebSocket server uses the native dispatcher for every policy; custom split transports retain their synchronous receive pump. The bind_websocket regression tests cover an exact-2024 handler awaiting ctx.sample or ctx.list_roots (including a synchronous handler that bridges with block_on) receives the client's reply, and a client without the capability gets a typed refusal instead of a hang. Non-Unix stdio, unsplit custom transports, and SSE still 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. Providers can attach bounded, clone-shared live policy constraints with AuthContext::with_verification_cancellation. Revoking a constraint denies queued authentication receipts, the next guarded request or Task operation, and retained SSE delivery, including revocation during an asynchronous revalidation. ManagedJwtResourceVerifier retires previously returned facts on successful key replacement or explicit trust revocation. Facts keep their original expiry and identity; policy constraints do not become cache keys, serialize as authority, or cancel sibling requests. Already-running application code is not preempted. Complete authorization 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.
  • Task creation needs an application supervisor. Configure ServerBuilder::task_supervisor(Arc::new(supervisor)) to host an ApplicationTaskSupervisor on the default runtime or the runtime supplied by final_tasks. The server starts the service within the caller-owned serve lifetime, waits for readiness, and settles it on exit. The shipped echo_server uses this hook. A server without a ready service still refuses creation with Final task creation requires an installed ready task service. Applications may instead install and drive AuthorizedTaskServiceRunner explicitly; combining that installation with the builder hook is rejected. Each elected attempt receives a separate child region in the caller's runtime. Its deadline is capped by the caller and the remaining attempt, total-lifetime, and retention limits; lease renewal cannot extend it. Cancelling a Task leaves the service and sibling Tasks independent. The built-in store keeps execution capacity reserved until the attempt and its descendants settle. Custom stores must provide equivalent admission across lease expiry and changes of owner. Descendants must cooperate with cancellation; dropping the service requests cleanup owned by the caller's runtime, and abrupt runtime destruction does not prove cleanup completed.
  • Running Tasks can publish status messages. An elected mutable FinalTaskInitialWork or FinalTaskAcceptedInput can call update_status_message(Some("Processing the next batch".into())) while continuing its work. Passing None clears the message. Each accepted update advances the record version, refreshes lastUpdatedAt, and publishes the matching Tasks status notification. It preserves the invocation's input, execution permit, lease and deadlines, so the same worker can later request input or finish. Current authorization, cancellation and the elected fence are checked before a write. The built-in store supports this path; custom stores must implement the atomic working-status and handoff-continuity hooks.
  • Authenticated local Tasks retain their caller: task creation atomically stores a private principal binding, original tool registration, and immutable creation generation. Protected task-producing tools require both ServerBuilder::task_access_authorizer for current request grants and ServerBuilder::task_execution_authorizer for current autonomous execution grants. Execution policies are bounded application callbacks that recheck owner/operation permission, expiry, and revocation before application work, while it is pending, and before accepting a transition through a Task handoff. FinalTaskAccessMetadata::principal_for_auth derives an identity lookup key from verified authentication facts; that key is not itself an execution grant. Policies must consult current trusted application state and must not retain an ingress context or credential. A refreshed credential for the same owner can access the task when its current request grants permit it. Custom stores must preserve the identity and operation metadata atomically with every snapshot. Context-free runtime and subscription APIs are trusted embedding controls. These controls are process-local; durable authorization, external revocation discovery, anonymous client isolation, and proxy Tasks ownership remain unqualified.
  • Proxied Tasks keep their original tool authorization. Install ServerBuilder::task_access_authorizer, with_scope_authorization, or with_operation_scope_authorization on the gateway before protected Task creation. The gateway binds each issued handle to the exact originating tool registration and rechecks current original-operation and management grants before upstream controls, reconciliation reads, and subscription events, including queued aliases. An unauthorized selection opens no upstream listener. These policies govern the current gateway process; they do not authorize an upstream worker's execution lifetime or provide restart recovery.
  • Proxied Task capacity can be divided among callers. Before installing a ProxyClient in the gateway, call proxy.with_task_limits(ProxyTaskLimits::new(128, 8)?)? to allow at most 128 handles on that upstream route and eight per stable authenticated owner. Both limits include pending creation reservations, so a rejected call sends no upstream tools/call. Client clones and rebuilt relays share the same accounting and limits; configuration becomes immutable when a Tasks relay is admitted. Completed handles, aliases, and expired snapshots retained for authoritative recovery continue to consume capacity until their mappings are reclaimed. The default remains 128 handles per route and per owner.
  • Proxied Tasks require a finite retention contract. Before installing the client, configure ProxyClient::with_task_retention_policy with ProxyTaskRetentionPolicy::new(maximum_upstream_ttl, mapping_lifetime). Both durations must be positive, the upstream maximum must fit the mapping lifetime, and the mapping lifetime cannot exceed 365 days. For example, Duration::from_secs(86_400) and Duration::from_secs(2_592_000) declare a one-day upstream maximum within a thirty-day local mapping ceiling. The ordinary builder methods as_proxy_with_task_retention and as_proxy_raw_with_task_retention accept the same policy directly; they are also available through the modern and auto facades. The upstream maximum is a trusted deployment contract, not a value accepted from peer discovery. A missing contract prevents Task creation from reaching the upstream, and clones share an immutable policy after relay admission. Arbitrary remote upstreams cannot use null-TTL Tasks under this profile. Contract violations and permanent ambiguity produce an explicit UpstreamStateUnknown outcome with a bounded, redacted, process-local orphan audit available through task_orphan_audit. An authorized best-effort cancellation request does not establish that upstream work has stopped. Gateway restart invalidates mappings; this profile provides neither shared durable mappings nor atomic administration across the two systems.
  • Task control requests validate approaching retention deadlines. The retention policy's renewal margin defaults to the smaller of thirty seconds and the configured upstream maximum TTL. Set it with policy.with_renewal_margin(duration)?; the margin must be positive and no greater than that maximum. Before an update, cancellation, or new listener, a snapshot inside this margin or past its cached deadline requires a fresh tasks/get. The caller needs current permission for both the requested action and that read, including after the read completes. Renewal runs within the caller's request and budget, and preserves the original mapping ceiling. An unavailable upstream prevents the requested control operation while retaining the mapping and its quota charge until the hard ceiling.
  • 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. Modern inspect --format json uses fastmcp.cli.inspect/v2 over both stdio and HTTP, retaining catalog titles, icons, annotations, resource sizes, prompt argument metadata, and _meta (including MCP Apps UI bindings), together with rich discovery identity and open capability fields. Retained fields preserve optional-field presence and numeric spellings within the existing redaction and size limits; truncation and schema completeness are reported explicitly. Exact legacy inspection keeps the v1 schema. 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.14.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::{auto::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. FastMCP does not create a runtime at this entry point. run_stdio_with_cx needs a blocking pool because its receive pump blocks on recv; that is a property of this entry point, not of the framework. On Unix you can instead serve reactor-driven process stdio with no blocking pool at all — see Non-blocking stdio. See Quick Start below for the dependency declarations.

auto::ServerBuilder serves MCP 2026-07-28 clients and also the exact 2024-11-05 initialize handshake that today's desktop clients and the MCP Inspector open with. modern::ServerBuilder pins a server to 2026-07-28 alone, so it refuses those clients.

Why FastMCP Rust?

Feature FastMCP Rust Manual Implementation
Async handler API #[tool] async fn plus handler trait hooks Manual Future boxing
Cancellation Local request checkpoints; live wire interruption remains unverified Application-specific checks
Timeouts Request and handler budget surfaces Application-specific timers
Concurrent-future ownership Context combinators poll caller-owned futures Manual ownership
Error handling 4-valued Outcome 2-valued Result
Boilerplate Generated handler/schema implementations Handwritten handler/schema implementations

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::{auto::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.

Area FastMCP Rust design
Handler API #[tool], #[resource], and #[prompt] macros plus explicit handler traits
Cancellation McpContext checkpoints and masks backed by asupersync
Timeouts Request and handler budget surfaces
Runtime asupersync only; Tokio adapters are unsupported
Outcomes Four-valued Outcome: success, expected error, cancellation, or panic
Unsafe code Forbidden in workspace crates with #![forbid(unsafe_code)]

Installation

From crates.io (current 0.14.0 package)

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

[dependencies]
fastmcp-rust = "0.14.0"

As a Git Dependency

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

Headless server embeddings (current source tree)

Direct fastmcp-server consumers can omit rich terminal output by disabling its default features. The console feature is default-on; an embedded modern server that supplies its own logger can use:

[dependencies]
fastmcp-server = { git = "https://github.com/Dicklesworthstone/fastmcp_rust", default-features = false }

Enable legacy-2024-11-05, tasks, apps, or the supported transport features explicitly as needed. These selections do not activate the server's console dependency. Headless servers retain request dispatch, protocol logging, statistics collection, and stats() / stats_collector(); they do not install a global logger or render banners, traffic previews, or statistics panels. ConsoleConfig, banner/traffic controls, and display_stats() require console. The idempotent without_banner() and plain_mode() helpers work in both profiles.

This removes the direct server's fastmcp-console / rich_rust rendering dependency. It does not promise a chrono-free graph: Tasks and OAuth use timestamps for protocol and security behavior. The fastmcp-rust facade retains its existing console-enabled behavior, so depend on fastmcp-server directly when that dependency boundary is required. This feature selection does not change the transport qualification boundaries described above.

Native HTTP readiness and draining (current source tree)

BoundHttpServer and BoundSecuredHttpServer expose GET /health for listener liveness and GET /ready for connection readiness. Configure their paths with HttpServerConfig::health_path and HttpServerConfig::readiness_path. Diagnostic paths must be distinct absolute paths and cannot overlap MCP, legacy SSE, or installed OAuth routes; invalid configurations fail before bind.

The readiness response is a bounded, Cache-Control: no-store JSON snapshot with schema fastmcp.http.readiness/v1. It returns 200 only while the listener is running, structurally ready, and has spare connection capacity. Saturation, draining, an unavailable snapshot, or an endpoint without a bound listener returns 503. The snapshot reports lifecycle, capacity, fixed counters, schemaVersion, and reason tokens; it contains no request identifiers or credentials and invokes no authentication provider or application handler. It observes capacity without reserving it.

A listener retains one bounded diagnostic connection when protocol capacity is full or admission is draining. This connection has an 8 KiB header limit, accepts no request body, and has one-second read and write bounds. It cannot become a protocol connection if capacity becomes available while it is open.

Keep the handle returned by bound.operator_handle() and call operator.begin_drain()? before cancelling the listener's serving context. The call fences new protocol admission and revokes unused reservations while accepted work retains its permits. /ready then returns 503, and /health remains available so a load balancer can observe the draining listener. Draining is irreversible for that listener generation; the call does not wait for requests to finish. A busy admission cell returns a retryable Busy error.

Native secured HTTP/HTTPS diagnostics retain the configured Host and Origin checks and support the corresponding GET preflight. They reject bodies, queries, duplicate security headers, and collisions with protected-resource metadata. TLS handshakes consume admission capacity; the extra diagnostic slot also has a one-second handshake allowance and retains its permit through bounded TLS shutdown. Its admission cannot become MCP or OAuth work later. The same operator_handle() and begin_drain() workflow applies to both listeners. Embedding adapters without a bound listener cannot report live connection readiness. These observations do not establish upstream availability, durable Tasks, or OAuth security qualification.

Bounded Prometheus diagnostics (current source tree)

Metrics are disabled by default. Install a separate diagnostic route with an explicit access policy on either native HTTP listener:

use fastmcp_rust::{HttpMetricsConfig, HttpServerConfig, McpResult};

fn http_config(scrape_token: &str) -> McpResult<HttpServerConfig> {
    Ok(HttpServerConfig::new().metrics(
        HttpMetricsConfig::bearer("/metrics", scrape_token)?,
    ))
}

The scrape credential is independent of MCP authentication. Only a purpose-specific keyed verifier is retained; authorization happens before snapshot capture. Use HTTPS or a trusted TLS terminator when transmitting the credential. HttpMetricsConfig::public("/metrics") explicitly permits public scrapes when that is the deployment's intended policy. Route collisions fail before binding, including OAuth and protected-resource metadata routes.

The GET response uses Prometheus text 0.0.4, Cache-Control: no-store, and a 16 KiB output ceiling. A successful capture returns 200 even during saturation or drain, so those conditions remain observable as gauges; an unavailable snapshot returns 503. Metrics share the single bounded diagnostic lane with health/readiness and release protocol admission before capture. Secured HTTP and HTTPS preserve their Host, Origin, framing, and diagnostic I/O limits.

The same prometheus_text() and prometheus_text_with_limit(bytes) methods are available on HTTP, client-executor, and stdio-output snapshots for application-owned exporters. Each contributor has 30 fixed series, prefixed fastmcp_operator_http_, fastmcp_operator_executor_, or fastmcp_operator_stdio_. The only label is the closed protocol profile; configuration generations, schema versions, lifecycle, readiness, capacity, and overflow are values. No endpoint, tool, principal, request, token, or error text becomes a metric label. Encoding performs no I/O, takes no admission permit, and never writes to protocol stdout. The built-in route exports the HTTP connection contributor; it does not infer Task, authentication, or upstream health from that snapshot.

Modern subscription admission (current source tree)

Modern subscription listeners share a server-wide capacity of 64 streams and a default limit of 32 streams per verified principal. Configure smaller bounds through the root, auto, or modern server builder:

let server = fastmcp_rust::modern::ServerBuilder::new("bounded-listeners", "1.0")
    .subscription_capacity(32, 8)?
    .build();

Both values must be positive; the per-principal limit cannot exceed the total, and the total cannot exceed 64. Token rotation, scope changes, request IDs, and new HTTP connections do not reset a verified principal's count. Anonymous listeners share one admission partition. These partitions govern capacity; existing authorization checks still govern event access.

Opening acknowledgements, active listeners, and retained callbacks or terminal drains consume capacity until their owners release it. Saturation rejects the new listen before acknowledgement without evicting an existing listener. In-process callers must drop finished listen handles to release their slots.

Subscription data events, including completed Task results, have an 8 MiB encoded-frame limit. The server retains at most 9 MiB / 64 events per listener, 64 MiB per principal, and 256 MiB across its subscription registry. Reservations cover recipient copies and remain held until active delivery callbacks return. Memory client listeners and stdio Task listeners retain at most 9 MiB / 256 events each and share a 64 MiB budget per connection. Consuming or discarding events releases their charges. An overflowing listener is retired independently, and late Task events cannot revive its retired owner. These limits account for encoded event ownership; they do not bound application-owned results or all temporary decoded allocations.

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.14.0, provides prebuilt fastmcp binaries on GitHub Releases. The fastmcp-cli source package is also available from crates.io for Cargo-based installation. Archives follow a fastmcp-<os>-<arch> pattern (.tar.xz on Unix, .zip on Windows).

This repository does not establish what the published archives are named. The checked-in release workflow is a quarantined verification surface and does not publish new GitHub Releases: it has held contents: read since 2026-08-02, and that permission cannot create a Release. v0.14.0 was built and published with the maintainer's local release tooling, not this workflow, so this repository does not establish whether those archives are downloadable either, and nothing in it can. That workflow's build matrix — the SURF-RELEASE-ASSET-CLOSURE rows in evidence/fnd-01/dependency-verification.toml — describes what the quarantined workflow would produce, which is not evidence of what the release contains; do not read it as the published filenames.

Take the exact filename from the v0.14.0 release page. The command below pins the tag rather than releases/latest — under a workflow that does not publish, latest is a moving pointer whose meaning is not stated anywhere. If the download does not resolve, build from source as shown above; that path is verified by this repository and the download is not.

# Replace <asset> with the exact filename listed on the v0.14.0 release page.
curl -fsSL -O https://github.com/Dicklesworthstone/fastmcp_rust/releases/download/v0.14.0/<asset>
tar -xJf <asset>
./fastmcp --version

CLI via Cargo (optional)

rustup toolchain install nightly-2026-08-25
cargo +nightly-2026-08-25 install fastmcp-cli --version 0.14.0 --locked

Manual CLI input continuations (current source tree)

fastmcp call, fastmcp read, and fastmcp prompt can complete MCP 2026-07-28 HTTP operations that return input_required. Each invocation sends one application request. Select the kinds of input you can answer with repeatable --input-capability options: elicitation-form, elicitation-url, roots, or sampling. These options advertise manual support; the CLI emits the request for review and waits for a separate, explicit invocation with answers. The default capability set remains empty.

For example, begin a tool call and save its result:

fastmcp call publish-report \
  --http-url https://example.com/mcp --protocol-policy modern-only \
  --input-capability elicitation-form --arguments-file arguments.json \
  --json > round-1.json

An input_required result intentionally exits nonzero, while preserving the result JSON on stdout. Check the saved document's resultType before resuming; a connection or protocol failure also exits nonzero. If inputRequests contains an elicitation keyed by approval, an answers file might contain:

{"approval":{"action":"accept","content":{"approved":true}}}

Use the exact keys and response shapes requested by your server. Repeat the original endpoint, command, target, arguments, and capabilities when submitting the saved challenge and answers together:

fastmcp call publish-report \
  --http-url https://example.com/mcp --protocol-policy modern-only \
  --input-capability elicitation-form --arguments-file arguments.json \
  --resume-result-file round-1.json --input-responses-file answers.json \
  --json > round-2.json

The CLI validates the saved result and correlates every supplied answer before contacting the server. Valid partial answers are accepted. If the server returns another input_required, use that new result for the next explicit invocation; its opaque requestState is forwarded unchanged. A result containing only requestState requires an explicit empty {} answers file and sends no inputResponses member. The server validates whether its state belongs to the repeated operation and caller.

Both files must be readable regular files without duplicate JSON members. The saved result is limited to 6 MiB and answers to 1 MiB. --json preserves unredacted result content, including continuation state. Resume files and manual input capabilities require an explicit HTTP endpoint with modern-only policy; they cannot be used with Auto negotiation, legacy routes, or a newly spawned stdio server. Timeouts and peer errors exit nonzero without replaying the action.

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. Native WebSocket request sends have their own absolute bound and observe request-local cancellation while writing; an interrupted partial frame retires the connection without flushing its suffix. 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(cx, "my-mcp-server", &[])
        .await
}

Supervised stdio recovery (Unix)

modern::ClientBuilder::connect_supervised_stdio_with_cx creates an explicitly supervised subprocess connection. Use client_mut() for application operations and call recover(cx, cancellation) after a confirmed subprocess exit. Recovery cleans up the failed generation, waits with bounded exponential backoff and jitter, starts a replacement from frozen command, arguments, environment and working directory, and completes fresh modern discovery before publishing a new generation.

use fastmcp_rust::{Cx, StdioRestartError, StdioRestartPolicy, SupervisedStdioClient, modern};

async fn connect_supervised(cx: &Cx) -> Result<SupervisedStdioClient, StdioRestartError> {
    modern::client_builder()
        .connect_supervised_stdio_with_cx(cx, "my-mcp-server", &[], StdioRestartPolicy::default())
        .await
}

The default policy permits three replacement attempts in a sixty-second window, with a 100-millisecond initial backoff, a five-second cap, and equal jitter. Attempts and the recovery deadline remain charged when a recovery future is dropped or cancelled. Dropping an in-progress discovery retains its replacement child for resumption; explicit cancellation settles that child before another attempt. If a replacement naturally exits during discovery, another attempt can use the remaining original budget. Invalid or rejected discovery remains terminal.

An interrupted request carries StdioInterruptedRequest diagnostic evidence: its outcome is unknown and any reissue must be explicit. Recovery never repeats an application RPC or transfers old request handles to the replacement. Write-side disconnects notify old handles before the process status can be checked, so their diagnostic exit evidence can be absent; recovery still requires the connection owner's private OS exit proof. Protocol errors, application errors, timeouts, cancellation, explicit close, EOF from a still-running process, and unverified cleanup do not authorize a restart. The command configuration is frozen, but executable file contents are not snapshotted. Call close_with_cx to await final process cleanup.

To keep observing catalog or resource changes across a subprocess restart, open the listener through SupervisedStdioClient::open_subscriptions_listener, with the caller context, cancellation token, SubscriptionListenRequest (or SubscriptionFilter), and SubscriptionTimeoutPolicy. This explicitly opts one listener into recovery. Read its events through the supervisor's next_subscription_event_with_cx method.

After fresh discovery, recovery sends a new listen request and waits for a valid acknowledgement before publishing the replacement connection. Request IDs keep increasing across generations, including failed replacement attempts. StdioRecovery::catalog_subscription reports the old and new listener IDs when a listener was restored. This reports an observation gap: refresh the affected catalogs or resources before relying on new events, because events during the outage are not replayed. The new acknowledgement remains the first event the application receives, and it may accept a narrower filter than the old peer.

Explicit listener cancellation and consumed subscription-terminal events remove the recovery configuration. Dropping an in-progress restoration retains its one committed listen request; resuming recovery does not send it again. Invalid acknowledgements, subscription errors, and acknowledgement deadlines keep the replacement unpublished and settle its subprocess. Listeners opened directly on client_mut() and Tasks listeners require application-managed recovery.

Proxy upstreams

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.

With proxy and websocket-experimental enabled, an idle modern WebSocket client can also become a proxy upstream:

use fastmcp_rust::{AsyncWsClientTransport, Cx, modern};

async fn websocket_gateway(cx: &Cx) -> Result<modern::Server, Box<dyn std::error::Error>> {
    let transport = AsyncWsClientTransport::connect(cx, "ws://127.0.0.1:8080/mcp").await?;
    let upstream = modern::client_builder().connect_websocket_with_cx(cx, transport).await?;
    let proxy = upstream.into_proxy(1)?;
    let catalog = proxy.catalog_typed_with_cx(cx).await?;
    Ok(modern::server_builder("gateway", "1.0")
        .as_proxy_typed("remote", proxy, catalog)?
        .build())
}

The native adapter forwards tools, resources, resource templates, prompts and completion, including typed input_required continuations and exact unknown result fields. Matching progress and requested log notifications are forwarded while a request is running, without accumulating them in the retained queue. Requests share one cancellation-aware connection owner. Cancelling a queued request has no upstream effect, and an active request retains ownership until its native cancellation cleanup finishes. Keep the caller runtime alive for the connection. This adapter currently provides core requests; catalog/resource subscription relays and Tasks are not advertised. ProxyClient::from_websocket exposes the same adapter for callers using the lower-level native client.

Exact-2024 proxy invocations preserve complete upstream tools/call, resources/read, and prompts/get results, including content annotations, metadata, open fields, tool error content, and the invocation's prompt description. Custom handlers can provide these results through ToolHandler::call_legacy_result_async_in_request, ResourceHandler::read_legacy_result_async_with_uri_in_request, and PromptHandler::get_legacy_result_async_in_request. Mounted handlers and tool transformations forward these hooks; mounted resources rewrite their known URI fields while retaining opaque extension data. Ordinary handlers retain the checked conversion from their existing application result types.

Completion handlers preserve their result envelopes too. Modern completion/complete proxy results retain _meta, unknown result members, and exact JSON number spellings; exact-2024 results retain their opaque _meta. Custom handlers can override CompletionHandler::complete_final_result_async_in_request or complete_legacy_result_async_in_request to return these complete results. The defaults delegate to the existing request-owned completion value hooks. Mounted target handlers and server-wide fallback handlers forward the result hooks while rewriting the request reference to its original child name. The router still checks completion value limits, final totals, and the selected protocol era's metadata before emission. Target visibility, caller cancellation, handler timeouts, and panic handling also apply to these hooks.

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.

With websocket-experimental, high-level modern WebSocket catalog calls and initial resource reads reuse complete results while their peer TTL remains fresh. Entries belong to one connection, retain exact result metadata and unknown members, and report only their remaining TTL. Queued catalog/resource notifications are processed before a candidate hit; invalidation also fences responses already in flight. A full catalog traversal rebuilds a cached nonterminal prefix under its existing cumulative limits.

The direct, auto, and modern WebSocket clients expose final_result_cache_enabled, set_final_result_cache_enabled, final_result_cache_stats, and clear_final_result_cache. Disabling the cache does not pause TTL expiry or invalidation; clearing or closing the connection erases retained entries. Raw requests, tool calls, prompt retrieval, Tasks, input-required results, and MRTR continuations are not cached. Exact-2024 WebSocket calls keep their existing uncached behavior.

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.

Modern server continuations also have retained-payload limits. The default router admits at most 4,096 live continuations overall and 1,024 for one verified owner, with 64 MiB of retained payload overall and 32 MiB per owner. ServerBuilder::mrtr_retention_capacity(states_per_owner, bytes, bytes_per_owner) configures these bounds before startup, including through the auto and modern facades. Verified ownership spans connections and credential rotation; anonymous and unverified callers share one bounded partition. The accounting includes input schemas, descriptors, accumulated answers, and private handler state. A full partition refuses additional retained work without evicting another conversation; a rejected growing partial answer leaves its original continuation usable. Completion, cancellation, expiry, and listener shutdown reclaim the corresponding retained state. These are process-local payload limits, rather than allocator measurements or durable continuation storage.

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.14.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.

Test HTTP connectivity (current source tree)

A CLI built from the current source can test an HTTP server's negotiation, liveness, and advertised tools, resources, and prompts without starting a subprocess.

# Modern MCP endpoint
fastmcp test \
  --protocol-policy modern-only \
  --http-url https://mcp.example/mcp \
  --json

# Auto: supply the modern endpoint and both explicit legacy endpoints
fastmcp test \
  --protocol-policy auto \
  --http-url https://mcp.example/mcp \
  --legacy-sse-url https://mcp.example/sse \
  --legacy-message-url https://mcp.example/messages \
  --json

# Exact MCP 2024-11-05 over SSE and message POST
fastmcp test \
  --protocol-policy legacy-only \
  --legacy-sse-url https://mcp.example/sse \
  --legacy-message-url https://mcp.example/messages \
  --verbose

From a source checkout, replace fastmcp with cargo run -p fastmcp-cli --. Auto and legacy-only require the legacy-2024-11-05 feature. Auto requires all three endpoints and falls back only when negotiation permits it; an application failure after modern selection does not trigger a downgrade. The legacy SSE and message endpoints must share an origin. Omit the subprocess command when supplying HTTP endpoints.

For bearer authentication, add --bearer-token-file ./mcp-token.txt to the modern command. The file must be a regular file containing at most 16 KiB, and the modern endpoint must use HTTPS. Authenticated requests never fall back to legacy. Add --idle-timeout 10 --absolute-timeout 30 for shorter probe deadlines. The defaults are 30 seconds idle and 120 seconds absolute; accepted ranges are 1–300 and 1–900 seconds respectively. For HTTP, the absolute limit also bounds the complete connection handshake and each probe, including connection setup. These limits do not impose one deadline on the entire command.

Modern liveness uses server/discover; legacy liveness uses ping. Catalog probes fetch one bounded page for each advertised capability, mark unadvertised capabilities as skipped, and report when more entries were omitted. --json emits bounded, sanitized fastmcp.cli.test/v1 results with the negotiated protocol, probe outcomes, and local idle/absolute timeout sources. Failures before testing begins use fastmcp.cli.error/v2. Failed tests return a nonzero exit status; use --verbose for detailed text output.

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.

Caller-owned modern stdio workflows (current source tree, Unix)

The modern stdio facade exposes asynchronous catalog traversal, ordinary content operations, completion, liveness checks, and incremental listeners. Each method takes the caller's &Cx and an explicit &McpRequestCancellation, and yields between bounded receive turns.

For one page at a time, list_tools_with_cx, list_resources_with_cx, list_resource_templates_with_cx, and list_prompts_with_cx return the corresponding typed final page. They preserve include/exclude tag filters and an optional opaque cursor, reuse fresh results under the connection's invalidation rules, and do not fetch the next page automatically. Pass the returned cursor explicitly to continue.

The four list_all_*_with_cx methods return modern::CollectedCatalog. Its pages() contain complete FinalCoreResult values, retaining cache hints, metadata, unknown result members, and exact numbers. Traversal keeps opaque cursors intact and enforces cumulative page, item, byte, and elapsed limits, including the permitted cache rebuild. An error returns no partial collection; pass an absent initial cursor.

The modern HTTP facade exposes the same complete catalogs through list_all_tools, list_all_resources, list_all_resource_templates, and list_all_prompts. Each also has a _with_cancellation variant accepting a request-local McpRequestCancellation. One token and one absolute deadline cover all pages and the permitted cache rebuild. Cancellation interrupts a stalled page and takes precedence over a cache hit, while independently owned HTTP executions and the caller's Cx remain usable. The returned modern::CollectedCatalog retains every complete typed page.

use fastmcp_rust::{
    ListToolsParams,
    modern::{Client, Cx, FinalCoreResult, McpRequestCancellation, McpResult},
};

#[cfg(unix)]
async fn discover_and_call(
    client: &mut Client,
    cx: &Cx,
    cancellation: &McpRequestCancellation,
) -> McpResult<FinalCoreResult> {
    let catalog = client
        .list_all_tools_with_cx(cx, cancellation, ListToolsParams::default())
        .await?;
    eprintln!(
        "{} tools across {} pages",
        catalog.item_count(),
        catalog.pages().len(),
    );
    client
        .call_tool_result_with_cx(
            cx,
            cancellation,
            "index_workspace",
            serde_json::json!({"uri": "file:///workspace"}),
        )
        .await
}

call_tool_result_with_cx, read_resource_result_with_cx, and get_prompt_result_with_cx follow installed modern reverse handlers under one operation-wide absolute deadline. Install those handlers with ClientBuilder::modern_reverse_request_handlers. With no modern reverse handlers installed, the complete input_required result is returned. complete_with_cx and ping_with_cx provide the corresponding ordinary completion and liveness operations.

Initial complete resource reads use the same connection-local result cache as the synchronous typed resource API. Replays preserve result metadata and exact unknown fields while aging the peer's TTL. Before a replay, the sole stdio reader processes ready invalidations; partial frames, buffered input, or a busy peer force a fresh request. Cancellation also applies to cache hits. Input-required results and continuation rounds never populate this cache. The yielding path starts cache freshness at the beginning of the fetch, so wire and scheduling delay can shorten reuse but cannot extend the peer's TTL.

Use open_subscriptions_listener_with_cx and next_subscription_event_with_cx to interleave a live catalog listener with ordinary client requests. Dropping an event wait preserves the stream for resumption; explicit cancellation retires that listener.

With the tasks feature, the facade also exposes call_tool_outcome_with_cx, get_task_with_cx, update_task_with_cx, cancel_task_with_cx, open_final_task_subscription_listener_with_cx, and next_final_task_subscription_event_with_cx. Tool outcomes retain their distinct complete, task, and input-required branches. These controls do not imply persistent task storage.

Published request cancellation remains request-local. Deferred discovery keeps its own connection-level cancellation rules, and dropped request cancellation is flushed by the next drive, send, or close. Subprocess creation and bounded pipe writes retain their synchronous limits.

Explicit cancellation for exact-2024 stdio requests (Unix)

The sealed legacy_2024::Client supports a separate McpRequestCancellation token for tool calls, ping, logging-level changes, and resource subscribe/unsubscribe requests through their *_with_cx_and_cancellation methods. Each method takes the caller's &Cx followed by &McpRequestCancellation, then its ordinary arguments.

The component-level request_legacy_core_with_cx_and_cancellation accepts the same token with a typed LegacyCoreRequest. It keeps the caller and token attached to the execution before publication, including while the future is parked. A pre-cancelled token sends no application request. After initialization, cancelling or dropping one published request retires that execution; queued cancellation controls are serviced on the next drive, send, or close. Cancelling a published initialization handshake retains its connection-level cleanup behavior.

Responses still use exact-2024 decoding from their admitted wire source. Control acknowledgements must be empty, modern result discriminators are rejected, and resource updates or log messages received while waiting remain available through the typed notification accessors. Ordinary peer errors and tool-level error results keep their existing request-local behavior. Response waits yield on the caller's runtime; bounded pipe writes and subprocess creation remain synchronous.

Live exact stdio progress (current source tree, Unix)

Modern stdio clients can observe progress while awaiting a tool, resource, prompt, or completion result. The client generates and owns a progress token, validates matching updates, and calls your observer on the caller's runtime. Delivered updates are consumed immediately, so a long-running operation can report more than the client's 64 retained diagnostic entries without filling that queue. Progress and total retain their original JSON numeric spelling; use as_str() when values must remain exact.

use fastmcp_rust::modern::{
    Client, Cx, FinalCoreResult, McpRequestCancellation, McpResult,
};

#[cfg(unix)]
async fn index_with_progress(client: &mut Client, cx: &Cx) -> McpResult<FinalCoreResult> {
    let cancellation = McpRequestCancellation::new();
    client
        .call_tool_result_with_progress(
            cx,
            &cancellation,
            "index_workspace",
            serde_json::json!({"uri": "file:///workspace"}),
            |update| {
                eprintln!(
                    "progress={} total={:?}",
                    update.progress.as_str(),
                    update.total.as_ref().map(|total| total.as_str()),
                );
            },
        )
        .await
}

The corresponding methods are read_resource_result_with_progress, get_prompt_result_with_progress, and complete_with_progress. For ordinary core catalog operations, the underlying fastmcp_client::Client also offers request_core_with_progress_with_cx; that method rejects caller-supplied _meta.progressToken values because it owns token allocation.

Keep observers short and nonblocking. A caught observer panic produces a sanitized error; cancellation, timeout, or dropping the published request retires only that request and preserves unrelated requests. Dropping queues wire cancellation for the next client drive, send, or close. Deferred discovery retains its separate connection-level cancellation rules. These methods send one request and preserve the complete typed result, including input_required, without automatically continuing MRTR or advertising Tasks. They use the existing yielding receive path; subprocess creation and bounded pipe writes retain their synchronous limits.

Calling a tool and waiting for its Task (current source tree, optional)

On Unix, build the CLI with --features tasks and use call --wait to keep the originating stdio process or HTTP client alive while an accepted Task finishes. The peer must support the Tasks extension, and the protocol policy must be explicitly modern-only:

fastmcp call generate-report --wait --protocol-policy modern-only \
  --server ./report-server --arguments '{"format":"pdf"}' --timeout 120 --json

fastmcp call generate-report --wait --protocol-policy modern-only \
  --http-url http://127.0.0.1:8000/mcp \
  --arguments '{"format":"pdf"}' --timeout 120 --json

The CLI sends the creating tool call once and prints its accepted Task receipt before waiting. It observes that Task through the same client and request-ID allocator, honoring the initial and subsequent pollIntervalMs values. An immediate complete result or already terminal Task produces one JSON line. A working Task produces its creation receipt followed by the latest admitted Task snapshot when observation ends. The latter has no resultType wrapper or copied creation-envelope metadata; completed result source is preserved. Treat this output as newline-delimited JSON, including on a failed command.

Successful completion exits zero. Failed or cancelled Tasks, completed results with isError: true, input-required pauses, expired retention, and local observation failures exit nonzero. The accepted receipt remains available even when observation fails. Waiting submits no input, repeats no tool call, and does not send tasks/cancel. Manual input capabilities and continuation files cannot be combined with --wait.

One --timeout covers connection setup, the creating call, and observation. Each admitted Task output has a separate settlement of up to 250 ms for ordinary Unix pipes and sockets; regular files and devices retain their OS I/O behavior. Stdio cleanup is also bounded and may finish after the active-work deadline. A blocked output pipe fails without starting another request. The CLI cleans up a child it started, so recovery of a process-local stdio Task after exit still requires server-owned persistence. This command does not add durable Task storage or automatic reconnects.

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 default binaries do 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 and exits successfully if the task is already completed, failed, or cancelled. Otherwise it subscribes to live updates and reads the task again after subscription acknowledgement, so a terminal change during subscription setup is also reported. It ends successfully on a terminal update or after --max-events updates. Each successful exit includes a watch-ended event; ending a watch does not cancel the task. It does not reconnect or promise replay across disconnects. --timeout defaults to 30 seconds, and timeout is a failed command. 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.

Observing a Task returned by a tool

With tasks enabled, a Tasks-aware tool call returns FinalToolCallOutcome::Task(created) when the server accepts asynchronous work. For HTTP, HttpClient::call_tool_final_outcome_with_cancellation checks that the peer supports Tasks before dispatch and returns the complete, Task, or input-required outcome from exactly one tool call. It does not invoke installed input callbacks. Unix stdio offers the corresponding call_tool_final_outcome_with_cx method.

Use FinalTaskHandle::from_created(&created) to retain that Task on the same client without sending an extra tasks/get or repeating the tool call. The creation receipt remains yours, including its metadata and unknown envelope members; the handle retains the exact Task result.

The handle's wait, wait_with_stdio, wait_with_memory, and wait_with_websocket methods respect the accepted Task's initial pollIntervalMs before their first read. They stop at terminal state, input-required, local cancellation, expiry, or the configured finite bounds. Waiting does not answer input or cancel remote work. Keep using the original client and authenticated identity. This in-process handoff does not persist a Task or establish permission to use it through another client.

Subscription-assisted Task driving (current source tree, optional)

With tasks enabled, a retained FinalTaskHandle can become a FinalTaskDriver through into_driver(FinalTaskDrivePolicy). Its drive_watching method combines native HTTP Task notifications with bounded polling and installed input callbacks. drive_watching_with_memory provides the same workflow through the Memory dispatcher. Unix stdio uses drive_watching_with_stdio; WebSocket uses drive_watching_with_websocket with websocket-experimental enabled. Configure the client's roots, sampling, and elicitation callbacks before connecting. The modern facade's stdio, HTTP, and WebSocket clients expose this as drive_final_task_watching.

The driver can answer newly requested input and observe completion directly from the subscription. Authoritative reads cover the attach/listen gap, acknowledged input updates, ambiguous notification timestamps, and silent streams. Reads respect the Task's latest pollIntervalMs. One invocation budget covers subscription setup, waiting, reads, callbacks, and updates; with_maximum_notifications also bounds repeated notifications.

Keep the same driver when continuing a Task. Its lifetime input ledger prevents an already answered input key from invoking a callback again, including after a partial update or a switch between watching and polling. Dropping or cancelling input resolution preserves an interruption latch and requires explicit reconciliation before further automatic callbacks. An empty accepted filter or a normal subscription terminal falls back to bounded polling once; an interrupted or malformed stream returns its error. The driver never reconnects, replays an uncertain update, or cancels the remote Task merely because local observation ends.

Stdio and WebSocket share each connection's existing reader between Task notifications and authoritative reads, preserving a partially received frame when a poll becomes due. An existing Task listener is left intact and prevents the driver from opening a second one. Clean cancellation or dropping the driver retires its exact listener while preserving independently owned catalog listeners; a broken transport still follows its normal connection-failure rules.

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(cx, endpoint)
    .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.

Built-in OAuth client secret verification (current source tree)

With builtin-auth-server, confidential client secrets use Argon2id v19 with 64 MiB of memory, three passes, one lane, a fresh 16-byte salt drawn by the core's fallible OS-random boundary, and a 32-byte output. Registrations retain the encoded PHC verifier instead of the original secret. Verification admits only this exact policy, salt width, output width, and bounded canonical PHC encoding before allocating Argon2 memory; imported higher costs and weaker parameters are rejected.

The issuer runs this work on a dedicated Asupersync blocking pool. Two jobs can hash concurrently, with at most 32 admitted jobs and 64 admissions per one-second window. An admitted caller waits at most 30 seconds and checks its runtime cancellation and deadline while waiting. Cancelling a waiter does not release a running job's quota until its secret and work retire. Overload or unavailable verification returns an explicit availability error. Unknown clients, wrong authentication methods, and public-client exchanges perform bounded dummy verification and share the same KDF admission budget.

Credential work holds no issuer-state lock. After verification, the issuer revalidates the client's exact registration under the guard that reads or commits state, so a result from a removed registration cannot authorize its replacement. Cancellation is checked again before consuming codes, rotating refresh tokens, or committing token and revocation state.

Native OAuth HTTP routes require an admitted blocking worker and refuse expensive dispatch with 503 when none is available. Immutable authorization server metadata remains available without that worker. Listener cancellation is forwarded to the route's context, and connection ownership continues until the blocking callback retires. Application callbacks must still cooperate with cancellation. The synchronous OAuthServer APIs wait for KDF completion; async embedders must call them from a blocking lane.

The profile without builtin-auth-server retains its development-only salted SHA-256 verifier. This change does not promote the in-memory issuer to durable or production-qualified OAuth/OIDC support.

Enterprise authorization components (native, opt-in)

Enable enterprise-auth to use fastmcp_rust::http_auth::enterprise. Its modules keep independently configured trust, OIDC code-flow handling, cryptographic verification, response admission and local identity resolution separate:

  • policy::EnterpriseProfile::from_documents admits both authorization servers and both preregistered clients. It checks their exact issuers, endpoints, grant declarations and confidential-client methods. OIDC and ID-JAG signing authority are configured separately.
  • keys::EnterpriseKeySource fetches both configured JWKS endpoints through credential-free guarded HTTPS under the caller's context. It returns separate OIDC and ID-JAG key owners together, bound to the frozen profile and their independent key generations.
  • oidc::OidcCodeFlowConfiguration admits the strict web/code/query/S256 registration and the original IdP permission to request openid. It generates independent state, nonce and verifier values under the caller's capability and time budget, then serializes an exact authorization GET.
  • verification verifies real RS256 signatures under distinct OIDC and ID-JAG key types. It checks exact audience/client/resource bindings, configured tenancy, nonce, optional OIDC at_hash, and bounded lifetimes. NumericDate fractions and exponents are evaluated exactly without floats.
  • response composes that verification with bounded HTTP/JSON admission. OIDC code responses, ID-JAG responses and final access-token responses have distinct accepted shapes. Signed scope narrowing must agree with the top-level grant, and the final response must name the exact scalar resource and explicit scope subset.
  • identity::EnterpriseSubjectMappingTable resolves the verified OIDC and ID-JAG subjects through an immutable, preexisting mapping table. Its reviewed snapshot fixes three distinct registration roles, explicit tenant relationships, trust domains and client-ID scope. Pairwise subject strings may differ; matching text never creates an account association. Lookup is bounded and uses an ordered index, with no create, link or update operation.
  • replay::IdentityAssertionReplay consumes a verified assertion and composes persistent MAC derivation, a registered restore-authority write intent, an atomic assertion-use store, and independent commit acknowledgment. It returns an exclusive reserved assertion only after the complete transaction succeeds.

The native OIDC sequence is OidcCodeFlowConfiguration::prepare → PreparedOidcAuthorization::admit_callback → EnterpriseExchangeDriver::exchange_oidc_code_for_identity. Callback admission checks the exact route, state, issuer and decoded parameter uniqueness. The driver consumes the code grant, adds the preregistered Basic or secret-post client authentication, and posts to the original IdP endpoint through guarded HTTPS. The form contains the grant, code, redirect URI and PKCE verifier; MCP scope, resource and audience fields are never added to this code grant.

The response validator retains the generated nonce and selected client/tenant expectations, and verifies the real ID-token signature and optional access-token hash. Profile, response-policy or key-generation drift is rejected before any POST. Dispatch shares the driver's single-flight slot and is bounded by the code's original expiry, the caller's budget and the fetch policy. Redirects and automatic retries are refused; each outcome consumes the code grant.

A successful identity still needs IdentityAssertionReplay::reserve before exchange_identity_for_id_jag can redeem it. Its sealed result retains the original verified OIDC identity alongside the verified ID-JAG. The subsequent exchange_id_jag_for_access_token requires the current EnterpriseSubjectMappingTable and an independently selected expected snapshot. It resolves that exact same-flow subject pair before constructing the resource-AS authenticated request, and checks the mapping again through dispatch and response admission. An absent row, changed subject, expired review or mismatched snapshot prevents redemption. Unequal pairwise subjects work only through an explicit preexisting row.

The resulting resource-bound credential retains the resolved local subject, snapshot and signed-token binding digests. Its usable lifetime cannot exceed either signed assertion or the mapping review. Code redemption does not bypass the durable replay boundary, and successful mapping does not create or link an account.

To use that result with the native MCP HTTP client, create an http::EnterpriseHttpPolicy from the same admitted EnterpriseProfile, the independently selected current identity snapshot, and the independently established monotonic freshness deadlines for the IdP and resource-AS metadata. The token's subject binding must match that policy snapshot exactly. Then consume the exchanged token with EnterpriseBoundAccessToken::into_http_credential(&policy, now, wall_now) and pass the result to modern::ClientBuilder::http_bearer_credential.

The builder carries the exact io.modelcontextprotocol/enterprise-managed-authorization: {} client declaration on discovery and subsequent modern MCP requests. Existing Tasks, Apps, and application extension settings are preserved. A conflicting nonempty enterprise declaration is rejected. This authorization overlay does not invent a server/discover capability or extension descriptor.

Keep the policy owner alive for the client's lifetime. Revoking, replacing, or dropping it invalidates every credential lease, including a request prepared before revocation. Policy replacement must advance its policy generation and cannot roll back metadata, registration, key or identity snapshot generations. Changing the identity snapshot requires advancing its generation; a rejected replacement leaves existing leases unchanged. The complete exchange profile, identity snapshot and original metadata document identities must match, and the earlier metadata deadline can only shorten the token's original lifetime. Raw HTTP requests must carry the exact current declaration in their encoded metadata before the credential can be attached; the target-only credential accessor withholds policy-bound enterprise tokens. Raw notifications and replies use ModernHttpRequest::control to omit request-only routing headers. This is the post-exchange MCP HTTP path; browser custody, deployment-provider qualification, SAML, and built-in enterprise token issuance retain their separate implementation gates.

Protecting a native HTTP resource

The facade's enterprise-auth feature also enables the resource-server path. Create an EnterpriseResourceConfiguration with the exact IdP and resource-AS issuer/token-endpoint pairs, the canonical MCP resource, and nonzero policy and metadata generations. EnterpriseResourcePolicy::new admits both bounded, duplicate-free metadata documents and their original monotonic freshness deadlines. The IdP must advertise token exchange and the ID-JAG requested token type; the resource AS must advertise the ID-JAG grant profile and JWT bearer grant. Metadata provenance remains the deployment's responsibility.

Install the policy through the ordinary authentication hook:

use fastmcp_rust::{
    EnterpriseResourceError, EnterpriseResourcePolicy, modern::ServerBuilder,
    providers::JwtResourceVerifier,
};

fn protected_server(
    policy: &EnterpriseResourcePolicy,
    verifier: JwtResourceVerifier,
) -> Result<ServerBuilder, EnterpriseResourceError> {
    Ok(ServerBuilder::new("enterprise-resource", "1.0")
        .auth_provider(policy.provider(verifier)?))
}

The independently provisioned JwtResourceVerifier must match the configured resource-AS issuer and MCP resource. It verifies the real RS256 signature, at+jwt token type, issuer, resource audience and lifetime on each access token. Every modern MCP request must also carry the exact official enterprise declaration with {} settings. The provider accepts only native HTTP Authorization; an extension declaration, ID Token, or ID-JAG cannot substitute for a verified resource access token. This profile adds no server/discover RPC extension descriptor.

Keep the policy owner alive while the server is serving. Revocation, owner drop or successful policy replacement invalidates previously issued authentication leases as well as new admission. Replacement advances the policy generation, rejects metadata generation rollback, and cannot change the resource or its token issuer. JWT key replacement and revocation independently retire leases from the old key generation. Refreshed authorization preserves the same verified owner identity, so rotation does not strand an otherwise authorized Task. These leases are enforced at request, Task and output checkpoints; already completed application effects cannot be recalled. SAML, browser custody, built-in enterprise issuance and durable deployment qualification remain separate work.

The lower-level OidcCodeGrant::write_token_form and OidcCodeResponseAdmission::admit_token_response remain available to embeddings with their own dispatcher. That codec writes to a caller-selected confidential sink, which can observe the code/verifier and must erase its buffers. A partial write cannot produce a response-admission owner. The authorization URL still requires an external browser adapter; local byte digests do not establish browser-launch provenance or durable callback custody.

For native signing-key acquisition, construct keys::EnterpriseKeySource with the admitted profile, a GuardedHttpFetcher, and a nonzero fetch-policy generation. Configure at most 64 KiB per response and a fetch deadline no greater than 30 seconds. Reuse or clone the source so overlapping calls share its single acquisition slot.

Calling fetch(cx).await makes separate GETs for the configured OIDC and ID-JAG sources, even when the operator explicitly selects the same URL for both purposes. The entire pair shares one original deadline and the caller's authority. Redirects, malformed documents, mismatched transport provenance or failure of either fetch prevent publication of the pair. Cancellation and abandonment retain the acquisition slot until guarded child operations settle.

The returned EnterpriseVerificationKeySet exposes profile(), oidc() and id_jag() for the existing signed-response consumers. Its observations retain the exact endpoints, document digests, key generations and guarded TLS provenance. Refresh is explicit; key identifiers in peer tokens cannot initiate network requests.

With an already-admitted profile, purpose-bound ID-JAG keys, and a response obtained from the selected trusted endpoint:

use std::time::SystemTime;
use fastmcp_rust::http_auth::enterprise::{
    response::{EnterpriseResponsePolicy, EnterpriseTokenResponse},
    verification::{ResourceTenantExpectation, TenantExpectation},
};

let admitted = profile.admit_id_jag_response(
    EnterpriseTokenResponse { status, headers, body },
    &id_jag_keys,
    TenantExpectation::SingleTenant,
    ResourceTenantExpectation::SingleTenant,
    EnterpriseResponsePolicy::default(),
    SystemTime::now(),
)?;

The result distinguishes success, a redacted OAuth denial, and a bounded first-stage step-up indication. Step-up never automatically launches a browser or reuses an assertion. Successful owners keep compact tokens private in zeroizing memory and have no Clone, Debug, serialization or bearer-header conversion. An admitted ID-JAG owner is consumed when validating a final response; its original scope request, signed IdP grant and final grant remain separate. Missing cache-prevention headers produce bounded diagnostics, while conflicting or explicitly cacheable policies are rejected.

Optional signed ID-JAG disclosures require an explicit verification::disclosure::IdJagDisclosurePolicy for the exact IdP and resource-AS relationship. The current schemas cover email, auth_time, acr and amr; each permission has a reviewed purpose and the policy has a finite review window. Use verify_id_jag_with_disclosure or EnterpriseProfile::admit_id_jag_response_with_disclosure to select it. Values are validated and discarded. Only admitted claim names and the configuration digest remain, and review expiry bounds later response admission and the locally retained final token. The ordinary verification method keeps its closed claim set; actor, subject-alias, RAR and sender-constraining claims cannot be enabled through this policy.

The native driver performs the three distinct grant exchanges, but complete enterprise sign-in still requires browser/callback custody and deployment qualification. These components do not activate the MCP extension. The mapping table supports public, redirect-host pairwise, and explicitly reviewed sector-document OIDC subject namespaces. It rechecks the current profile, selected snapshot, signed token bindings and review/claim lifetimes on every lookup; results retain the exact token and snapshot digests. A local snapshot digest does not establish a rollback-resistant policy fence or prove that responses came from one exchange.

For a preregistration that declares sector_identifier_uri, first call identity::OidcSectorDocumentReview::fetch with the complete relying-party registration, its explicit Client or ResourceAuthorizationServer role, and a GuardedHttpFetcher under the caller's context. This performs one bounded, credential-free HTTPS GET. The response must be an HTTP 200 JSON array containing every exact registered redirect URI. Additional document entries never authorize callbacks. The review binds the registration generation, issuer, tenant, client, role, redirect set, sector URL, exact document digest, fetch policy and observed TLS provenance.

Use oidc::OidcCodeFlowConfiguration::from_documents_with_sector_review to select one callback from that complete reviewed registration, including registrations with multiple redirect hosts. Use identity::EnterpriseSubjectMappingTable::from_trusted_configuration_with_sector_reviews to bind the independently reviewed client and resource-AS sectors into the mapping snapshot. Both consumers retain the frozen evidence and perform no refetch during ordinary authorization flows.

Protected persistent records

fastmcp_rust::persistent::PersistentBlobStore provides asynchronous create, read and replace operations over a configured external encryption provider, transactional blob store and registered restore authority. These operations use the caller's context and deadline and share finite operation and buffer budgets.

  • Creation inserts a new random record ID only if it is absent. Replacement compares the complete expected revision; it never performs an unrestricted upsert.
  • Every write durably prepares its restore intent before encryption. The store atomically commits the exact ciphertext, revision and intent under the durable restore fence, and the authority verifies the commit proof before the caller receives the new revision.
  • Reads require an exact PersistentBlobRevision retained in trusted application control state. Canonical framing, the admitted key generation, ciphertext digest and authenticated record context are checked before plaintext is released. Store data cannot choose a newer revision or substitute its own expected context.
  • BoundedPlaintext owns a zeroizing allocation. Returned plaintext retains its byte reservation until it is dropped or explicitly transferred to its caller. Limits account for allocation capacity, including spare capacity.
  • A failed comparison returns Conflict only after durable evidence proves that the losing operation cannot commit later and the authority settles its intent. Unknown outcomes leave the deployment closed for recovery.

PersistentEnvelopeBackend owns the complete persistent key, nonce and AEAD implementation. The facade accepts only canonical FMCPBOX version 1 with the XC20P suite and constructs typed FMCPENV authenticated context for the fixed protected-blob payload purpose. The encryption provider and blob store each have independently pinned artifact and configuration identities. No raw persistent key is passed into the process-ephemeral protector.

Applications retain the returned revision, including across restart, and implement the external provider contracts for their deployment. This is a protected-record storage API; native enterprise sign-in, durable OIDC flow orchestration, key-provider qualification and epoch migration remain separate work.

External replay and restore providers

The replay path has three independently implemented provider boundaries:

  • fastmcp_core::replay::PersistentHmacSha256Backend supplies persistent MAC creation and verification. PersistentReplayDigest constructs the exact purpose-separated input and derives aliases under every configured active and previous generation. Partial results never become an alias set.
  • fastmcp_core::restore::RestoreEpochAuthority supplies external store-set registration, current-epoch certification, write-intent preparation and completion. RestoreEpochFacade::register fixes the entire configured store union before releasing any RegisteredRestoreStore. Canonical stable binding digests exclude transient operation IDs, observation times and transport data.
  • replay::IdentityAssertionUseStore atomically checks and reserves the whole alias set, journals its exact outcome with the durable fence CAS, and returns a commit proof for the independent restore authority to verify. The client pins the store adapter's artifact and configuration identity as well as the MAC ring and its deployment acknowledgment identity.

Facade users can import the provider modules through fastmcp_rust::http_auth::enterprise::replay::{persistent_mac, restore_authority}.

The replay key depends on the exact verified issuer and compact-token digest. Changing flow, browser session, client registration or policy evidence cannot create a second key for the same assertion. Tombstones retain authority through the signed expiration plus the fixed global 300-second positive-skew ceiling; a later policy cannot shorten that horizon. Rotation looks up every admitted previous alias before allowing a new reservation.

IdentityAssertionReplay::reserve consumes the protected assertion on every outcome. Its caller-owned operation is bounded by the caller deadline, remaining assertion lifetime and a 30-second ceiling; store work is also bounded by the write intent's expiry. An uncertain write, malformed receipt, cancelled post-dispatch operation or abandoned fence closes the registered deployment to new writes and preserves unresolved external state. Dropping a local owner never releases a tombstone or automatically retries a mutation.

These contracts are implementable external boundaries, not bundled persistent services or attestations. The adapters must independently prove durable key custody, atomic all-generation reservation, cluster ring agreement, external rollback/clone resistance and authenticated commit verification. The shipped test adapters are explicitly in-memory fault fixtures.

RestoreEpochFacade::recover reconciles a bounded, snapshot-consistent view of unresolved writes through the exact pre-registered store union. Each independent RestoreStoreRecovery adapter must supply either the real durable commit proof or a durable terminal noncommit proof that fences out the original writer. A missing record, timeout or expired intent is insufficient. The authority verifies each proof against the original intent before settling it.

After process loss, RestoreEpochFacade::recover_after_restart accepts the original deployment configuration and complete store union without requiring an existing facade. It creates only quarantined internal handles, resolves the persisted intents, and performs ordinary authority registration only at the end. Every provider request must match the authority's previously registered deployment, configuration and store-set identity; recovery cannot bootstrap a new authority namespace or silently change an epoch.

Recovery permanently retires the old handles. A completed snapshot returns a summary; fresh handles are returned only if a new authority registration atomically refuses every remaining unresolved intent or closed deployment and every store retains its original stable epoch binding. A proved live CAS loser can use RegisteredRestoreStore::reconcile_write to settle its owned fence and return a normal conflict. Unknown outcomes remain unresolved. Administrative epoch advance and fenced migration remain unfinished.

Durable browser launch/callback custody, confidential credential providers, attested mapping authority and qualified deployments of the replay/restore providers remain required before activation. SAML and durable/distributed server Task stores remain separate incomplete extension work.

Sender-constrained credentials: DPoP (RFC 9449), caller-driven

fastmcp_rust::http_auth::dpop is a public, explicit, caller-driven API for DPoP. It is deliberately not wired into the bearer OAuth driver: its module documentation states that it "never promotes a DPoP token into the existing bearer-only OAuth driver" and "does not install automatic OAuth negotiation or HTTP retries". With the low-level session API, the application owns authenticated HTTPS I/O, response-size limits, and cancellation of in-flight I/O. The explicit native adapters described below can own those operations. The application chooses when to acquire a DPoP grant and whether to retry a nonce challenge; ordinary bearer operations never switch to DPoP automatically.

One session pins one HTTPS token endpoint, one exact HTTPS MCP resource, and one ES256 proof key. The two types a caller must name to open one — DpopKey, the first argument, and DpopError, carried by DpopClientError::Proof — are re-exported from this same module, so fastmcp_rust::http_auth::dpop is self-contained. They originate in fastmcp_protocol::dpop, which the facade does not forward, so without that re-export the API would be reachable without being constructible. The flow, in call order:

  1. DpopSession::new — pin the endpoint, resource and key. DpopSession::authorization_jkt exposes the key thumbprint for a confirmation claim.
  2. DpopSession::token_request_headers — build the headers for your token request, then perform that request yourself.
  3. DpopSession::admit_token_response — strict, bounded, duplicate-free admission of the response. It yields a DpopCredential, and refuses a bearer downgrade or a mismatched proof key rather than accepting one.
  4. DpopSession::resource_request_headers — build the headers for the MCP request, again performed by you.
  5. On a nonce challenge, feed the nonce back with DpopSession::observe_token_nonce or DpopSession::observe_resource_nonce and generate new headers for a retry you deliberately admit. Never replay a proof, and never automatically replay a possibly-executed MCP call.

DpopRequestHeaders::apply_to and DpopRequestHeaders::into_headers move the prepared fields onto your request. DpopCredential::expires_at, DpopCredential::revoke and DpopCredential::is_revoked cover lifetime and revocation; DpopSession::revoke irreversibly retires the session and every credential it issued. AS and RS nonce state are kept separate. Errors are the redacted DpopClientError variants — no peer text, URL, proof, token or response body is retained.

The full contract, including what each refusal means, is the module documentation on fastmcp_client::http_auth::dpop; read it before driving the flow, because several of the rules above are the caller's to honour rather than the library's to enforce. fastmcp_protocol::dpop holds the ES256 proof and RFC 7638 thumbprint primitives behind the jose feature. A bounded native HTTPS resource POST is available under the module's native submodule for callers who would rather not own that I/O.

Native DPoP authorization-code acquisition

http_auth::oauth::OAuthClient also provides explicit native-public-client entry points: authorize_dpop(cx, key, launch_browser) uses a loopback callback, and authorize_dpop_with_redirect_driver(cx, key, redirect_uri, driver) uses the host's independently registered HTTPS callback. The caller supplies the proof key and browser or callback driver. Both paths retain state, S256 PKCE, issuer, scope, resource, and exact callback checks; the authorization request binds dpop_jkt, and the bounded HTTPS token POST carries a fresh proof for that same key.

The result is oauth::dpop::DpopAuthorizationOutcome. Authorized owns the session and proof-bound access credential; into_parts transfers them to the explicit dpop::native::DpopHttpClient, whose resource TLS policy is selected separately. NonceRequired owns one in-memory continuation. After choosing to continue, consume it with retry(cx) for at most one token-endpoint nonce retry. It preserves the original code, key, cancellation, and deadline, also enforces a stricter supplied caller, and produces a fresh proof. An ambiguous transport failure does not authorize another retry.

This access-only flow rejects bearer downgrades, wrong proof-key bindings, scope expansion, and refresh, ID-token, or token-exchange response profiles. Authorization-server and resource-server nonces stay separate. No credential is converted to the bearer driver, and no browser process, automatic refresh, resource-operation replay, or durable callback custody is created.

Explicit rotating DPoP refresh

Public clients whose validated issuer registration and requested scopes permit refresh can select authorize_renewable_dpop or authorize_renewable_dpop_with_redirect_driver. These entry points retain the same callback and proof-key checks and require a valid refresh token in the initial response. The access-only entry points keep their existing response policy.

DpopAuthorization::into_renewable_parts returns the session, access credential, and exclusive DpopRefreshToken custody. An existing native resource client can renew in place with DpopHttpClient::refresh_authorization(cx, refresh_token). It retains the same HTTP transport, resource TLS roots, body-size limit, request timeout, nonce state and existing revocation handles. The token endpoint still uses its separately admitted issuer TLS policy. The consuming nonce continuation keeps the client mutably borrowed until explicitly retried or dropped, so no resource request can race the pending renewal.

For low-level session ownership, recover the original session with DpopHttpClient::into_session and call refresh_token.refresh(cx, &mut session). Both paths use the original issuer, client, token endpoint, resource, TLS trust and granted scope ceiling. Renewal cannot transfer to another session, even one with the same proof key and endpoints.

DpopRefreshOutcome::Refreshed contains a new access credential and a byte-distinct successor refresh token. A narrowed scope grant becomes the next refresh ceiling; an omitted scope preserves that ceiling. Existing access snapshots retain their original expiration. Access expiration permits renewal, while local credential or session revocation prevents it.

DpopRefreshOutcome::NonceRequired hands one consuming continuation back to the application. Its explicit retry(cx) retains the original transaction and deadline and produces a fresh proof. A second challenge is terminal. The authorization-server nonce remains separate from the resource-server nonce.

After renewal preflight succeeds, cancellation, a dropped future or continuation, a disconnect, or any rejected response revokes the complete session, including access snapshots from earlier rotations. The consumed refresh token is erased and never automatically replayed. Preflight refusal sends nothing and preserves existing access snapshots, although the consuming refresh owner is erased. Dropping unused refresh custody also erases only that secret. This API provides in-memory rotating custody; it does not provide persistent refresh storage, automatic login, nonrotating refresh, or automatic resource-call retries.

Protected DPoP Task restart

With the tasks feature, DpopHttpClient::prepare_task_restart consumes a complete TaskResumeRestartPlan of protected, owner-bound Task controls. The host supplies its current verified owner/profile binding and explicitly selects the DPoP client and credential. Saved records cannot select a login, endpoint, proof key, or TLS trust policy.

The returned DpopTaskRestart reconciles records sequentially through fresh authenticated discovery and tasks/get. The batch retains one deadline and one response-byte budget across records. Local expiry and remote unavailable results are explicit outcomes; operational errors and an abandoned read close that restart owner while retaining the pending record, any completed response, and unvisited records for inspection. The workflow does not replay Task creation, submit inputs, cancel remote work, or automatically open watches.

Handle a terminal application result before applying the item's conditional storage_change. An active replacement preserves the original local retention window, and writes compare the exact staged version. A changed checkpoint must be reconciled explicitly. Loading a plan stages the complete bounded selection before network work, so later checkpoint writes cannot invalidate an enumeration cursor halfway through recovery.

On Linux, a completed AsyncTaskResumeStore::try_load_restart operation can call prepare_persisted_dpop_restart to bind that staged selection and its protected store to the DPoP client. The returned PersistedDpopTaskRestart retains each application outcome until the host explicitly acknowledges it or takes it without persisting. An interrupted acknowledgement keeps the original storage job; the next acknowledgement observes that job instead of submitting a second write. A failed write retains the result, exact checkpoint change, and store for recovery through into_parts. Local acknowledgement has its own caller budget and does not renew the batch's remote authorization or retention window. Handle or durably save terminal results before acknowledging; a crash before acknowledgement can deliver the result again.


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.6.2"

3. Write Your Server

// src/main.rs
use asupersync::runtime::{RuntimeBuilder, reactor::create_reactor};
use fastmcp_rust::{auto::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

Non-blocking stdio (Unix, opt-in)

run_stdio_with_cx above is the portable default, and it is blocking: it hands run_stdio_pump to spawn_blocking and reads through StdioTransport::stdio() and AsyncStdout, whose own documentation records that they "perform blocking I/O internally. An async trait alone does not make those standard-stream operations nonblocking." Several stdio caveats in Limitations are consequences of that choice rather than of the framework, and the rows that describe only this entry point now say so. Others, such as the client-subprocess rows, are unrelated to it and still apply.

On Unix there is a second path. NativePipeReader::from_stdin and NativePipeWriter::from_stdout claim the real process descriptors, register them with the caller's reactor, and observe that caller's cancellation and deadline — no helper thread, no blocking pool, and no change to descriptor flags that is not restored on release. serve_stdio_io then serves the transport over them. modern::ServerBuilder is already modern-only, so no protocol-policy call is needed:

use fastmcp_rust::modern::ServerBuilder;
use fastmcp_rust::{NativePipeReader, NativePipeWriter};

// Note blocking_threads(0, 0): this path needs no blocking pool at all.
let runtime = RuntimeBuilder::current_thread()
    .with_reactor(create_reactor().expect("create I/O reactor"))
    .blocking_threads(0, 0)
    .build()
    .expect("create application runtime");
runtime.block_on(async {
    let cx = Cx::current().expect("application context");
    let server = ServerBuilder::new("native-process-stdio", "1.0")
        .tool(Echo)
        .build();
    let input = NativePipeReader::from_stdin(&cx)?;
    let output = NativePipeWriter::from_stdout(&cx)?;
    server.serve_stdio_io(&cx, input, output).await
})

That is the wiring, not a complete program: acquiring the second descriptor can fail after the first succeeded, and the two halves report io::Error while serve_stdio_io reports McpResult, so a real main has to reconcile both. crates/fastmcp-server/examples/native_stdio.rs does, including closing the already-claimed reader rather than implying a partial process binding was released. It is a checked-in target with no required-features; run it with cargo run -p fastmcp-server --example native_stdio.

Bind both endpoints to the same Cx that serves the transport. A pipe whose own context is cancelled or past its deadline reports a cooperative stop on every poll while the serving context stays live. The transport retries a bounded number of those and then fails the endpoint with a diagnostic naming this cause, instead of retrying without end.

What this does not claim. This is an opt-in transport pairing, not the default, and not an aggregate cancellation, quiescence, or conformance qualification — every boundary in Limitations still applies except where it is explicitly about the blocking default. from_stdin and from_stdout are #[cfg(unix)]; there is no non-Unix equivalent, because asupersync's readiness Source is socket-bound on Windows while Windows standard streams are handles.


Legacy sampling options in proxies

The exact-2024 stdio and HTTP reverse-request bridges carry text and image messages, model preferences, context selection, and provider metadata to the downstream sampling handler. Image data and MIME types retain their original strings. Responses preserve their declared user/assistant role and stop reason, including an omitted stopReason or a provider-defined value.

use fastmcp_rust::{
    SamplingIncludeContext, SamplingModelHint, SamplingModelPreferences,
    SamplingRequest,
};

let request = SamplingRequest::prompt("Summarize this result", 256)
    .with_model_preferences(SamplingModelPreferences {
        hints: vec![SamplingModelHint {
            name: Some("preferred-model".to_owned()),
        }],
        cost_priority: Some(0.8),
        speed_priority: Some(0.6),
        intelligence_priority: Some(0.9),
    })
    .with_include_context(SamplingIncludeContext::ThisServer);

Pass the request to ctx.sample_with_request(request).await. For image inputs, construct a conversation with SamplingRequest::new and SamplingRequestMessage::image(role, base64_data, mime_type). A conversation can mix text and image messages. A sampling handler can return SamplingResponse::image(data, mime_type, model) and select a role with with_role.

Both messages and responses expose one typed content field: SamplingMessageContent::Text { text } or SamplingMessageContent::Image { data, mime_type }. Match that enum when handling either kind. text_content() borrows text when present; SamplingResponse::into_text() extracts text or returns an error for an image.

Use with_metadata for a provider-specific JSON object. Leaving include_context unset differs from explicitly selecting SamplingIncludeContext::None; optional model preferences and metadata also retain their presence. The with_model_hints shorthand replaces only hints and retains any configured priorities.

For direct struct construction on SamplingRequest, the former model_hints field is now model_preferences; initialize include_context and metadata as well, or use the constructors and builders. The former message and response text fields are now typed content, and responses include an explicit role. Wider token budgets, content annotations, and exact request/result _meta preservation still require the protocol-specific APIs.

Typed extension handlers (opt-in, current source tree)

The extension-authoring feature adds typed extension settings, request and response schemas, and #[extension] handlers. Enable it from the current Git source; the dependency can be renamed, and no component crates are required:

[dependencies]
fm = { package = "fastmcp-rust", git = "https://github.com/Dicklesworthstone/fastmcp_rust", branch = "main", default-features = false, features = ["extension-authoring"] }

This complete program constructs and installs an asynchronous echo handler:

use fm::extensions::authoring::{ExtensionBuilder, ExtensionContext};
use fm::serde::{Deserialize, Serialize};
use fm::{JsonSchema, McpResult, extension, modern};

#[derive(Deserialize, Serialize, JsonSchema)]
#[serde(crate = "fm::serde", deny_unknown_fields)]
struct Settings {}

#[derive(Deserialize, Serialize, JsonSchema)]
#[serde(crate = "fm::serde", deny_unknown_fields)]
struct Message {
    value: u32,
}

#[extension(
    method = "com.example/echo",
    params_schema = "echo-params-v1",
    result_schema = "echo-result-v1"
)]
async fn echo(
    context: ExtensionContext<'_, Settings>,
    request: Message,
) -> McpResult<Message> {
    context.checkpoint()?;
    Ok(request)
}

fn main() {
    let builder = ExtensionBuilder::<Settings, Settings, Settings>::new(
        "com.example/typed-echo",
        1,
        "empty-settings-v1",
        "empty-settings-v1",
        Settings {},
        |_client, server| Ok(server),
    )
    .expect("admitted typed settings");
    let registration = EchoExtension
        .register(builder)
        .expect("typed handler registration")
        .build()
        .expect("sealed extension registration");
    let _server = modern::ServerBuilder::new("typed-echo", "1.0")
        .extension(registration)
        .expect("extension installation")
        .try_build()
        .expect("frozen server");
}

The resolver receives typed client and server settings and returns the effective settings exposed by context.settings(). The explicit serde(crate = "fm::serde") keeps the derives valid with only the renamed facade dependency. Use the resulting server with an existing caller-owned serve_* path to handle requests; the program above only constructs the server and creates no runtime or transport.

Activation requires both sides to opt in on each request. The server advertises the installed extension, and the client must include compatible settings in the request's _meta["io.modelcontextprotocol/clientCapabilities"].extensions object. For this example, that object contains "com.example/typed-echo": {}. Missing or incompatible settings refuse the call before the handler runs. Settings and request payloads are schema checked before callbacks; returned responses are schema checked before publication. Framework _meta is removed before decoding the typed request, so deny_unknown_fields applies to the application payload.

ExtensionContext provides typed settings, immutable descriptor information, cancellation and deadline observations, and checkpoint(). It exposes no raw McpContext, Cx, credentials, or registry access. One registration can contain multiple typed methods. Installation does not merge an existing extension registry. These construction and admission APIs do not imply complete extension qualification.

Use ExtensionBuilder::typed_notification (or typed_notification_sync) for a modern client-to-server notification. Registration requires an explicit operation authorization callback and a metadata key for a self-contained settings proof. Every message must supply compatible settings in that exact params._meta field; an earlier request's capabilities cannot activate a later notification. The framework authenticates each message, validates its typed payload, applies the operation policy, and resolves its settings before invoking the handler with an ExtensionNotificationContext. This context offers the same bounded cancellation and deadline observations without exposing transport or task-spawning authority.

Typed notifications run on caller-owned HTTP, stdio, memory, and WebSocket serving paths after the transport selects the modern era. HTTP returns an empty 202 only after the callback and its scope settle. Stream transports emit no JSON-RPC response for successful or rejected notifications. Pending notification work is cancelled and drained on connection shutdown, and each notification has a finite deadline even when ordinary request timeouts are disabled. Legacy extension notifications are outside this surface.

Calling extensions from clients

Configure ClientBuilder::extension_registry with the client's descriptor registry, local settings, and a compatibility-resolver factory before connecting. The connected HTTP and WebSocket clients, and the Unix stdio client, expose notify_final_extension(cx, extension_id, method, parameters), including the recommended modern facade. A retained StdioRequestExecutor can also publish a notification while other request handles remain live. The client attaches fresh settings proof in the exact location named by NotificationActivationProofDescriptor; applications do not have to construct that proof manually. Conflicting caller proof, unconfigured methods, wrong directions, and legacy sessions fail before publication. Notifications consume no request ID or response waiter. HTTP waits for the empty 202 acknowledgement; stdio, memory, and WebSocket publication does not imply that the server callback has completed.

On Unix, modern::Client::request_final_extension(cx, extension_id, method, parameters) also drives stdio extension responses cooperatively on the supplied runtime, including deferred discovery. Use request_final_extension_with_cancellation to retain an explicit request-local cancellation token along with the original caller context. A cancelled or dropped request leaves the connection reusable; its late response cannot complete a later request. Unregistered methods and wrong-direction calls are refused before publication, and successful responses must belong to the extension's admitted result owner. An intact result with the wrong extension owner fails that request; loss of the original result source retires the connection. Use close_with_cx(cx) for yielding, bounded subprocess and callback cleanup. The lower-level StdioRequestExecutor::execute_final_extension_with_cancellation provides the same cancellation ownership for separately retained request handles.

The in-process client now accepts the same frozen extension configuration through MemoryClient::builder(client_info).extension_registry(...). Connect it to an owned bounded memory endpoint with connect(cx, transport). Existing MemoryClient::connect calls continue to work for ordinary core methods; a raw extension capability advertisement alone does not authorize extension calls.

Use execute_final_extension(cx, cancellation, extension_id, method, parameters) to obtain a MemoryExtensionExecution, then drive it with next_extension_event(cx, cancellation, execution). Each handle retains its own progress, admitted result, cancellation, and exact result JSON source. Core and extension handles may share the connection, and driving one routes its siblings' responses without consuming them. request_final_extension is the convenience form that waits for the result. Memory notifications take the explicit cancellation token as well.

Memory publication waits for channel capacity while continuing to route incoming responses, including when both bounded directions are full. Dropping or cancelling an unsent wait allocates no ID or waiter. Dropping a published execution schedules its cancellation before later application messages, and late results remain owned by that execution rather than a sibling. These clients run on the supplied runtime and do not create a background pump. A caller timer driver is required for response deadlines and the finite send-admission timeout.


Forwarding typed extension requests over HTTP

With both extension-authoring and proxy enabled, a typed gateway can forward request/result extension methods to an independently configured modern HTTP upstream. Reuse the same complete extension declaration on both legs. The declaration's schema and contract checks remain inside the framework.

Within an asynchronous serving setup, the following uses Settings, Message, and EchoExtension from the example above. Supply your caller-owned cx and canonical upstream endpoint:

let make_builder = || {
    ExtensionBuilder::<Settings, Settings, Settings>::new(
        "com.example/typed-echo",
        1,
        "empty-settings-v1",
        "empty-settings-v1",
        Settings {},
        |_client, server| Ok(server),
    )
};
let declaration = EchoExtension.register(make_builder()?)?.build()?;
let upstream = modern::ClientBuilder::new()
    .connect_extension_http_upstream_with_cx(
        cx,
        endpoint,
        declaration,
        &Settings {},
    )
    .await?;
let registration = make_builder()?
    .typed_http_proxy_request::<Message, Message>(
        "com.example/echo",
        "echo-params-v1",
        "echo-result-v1",
        upstream,
    )?
    .build()?;
let gateway = modern::ServerBuilder::new("typed-gateway", "1.0")
    .extension(registration)?
    .try_build()?;

The connection helper consumes the declaration to configure discovery and typed settings negotiation; its local request callbacks are not invoked. Configure the upstream client builder's identity, credentials, TLS, and timeout policy before connecting. The gateway uses that configured upstream identity. Each forwarded call must match the registered contract and independently negotiated effective settings, and its request and result pass the typed schema checks.

The request/result route rejects contracts that declare notifications. To relay request-owned server notifications as they arrive, declare the same event on both legs and choose the explicit notification-aware route. This variant uses Message for the event payload as well:

let with_notices = || {
    make_builder()?.typed_request_notification::<Message>(
        "com.example/echo/changed",
        "echo-changed-v1",
        "com.example/echo-request-id",
    )
};
let declaration = EchoExtension.register(with_notices()?)?.build()?;
let upstream = modern::ClientBuilder::new()
    .connect_extension_http_upstream_with_cx(
        cx,
        endpoint,
        declaration,
        &Settings {},
    )
    .await?;
let registration = with_notices()?
    .typed_http_proxy_request_with_notifications::<Message, Message, Message>(
        "com.example/echo",
        "echo-params-v1",
        "echo-result-v1",
        upstream,
    )?
    .build()?;

The upstream server must advertise that same complete contract. Install the resulting registration on the gateway as above. Each event is bounded, checked against its schema, decoded and re-encoded through the declared Rust type, and checked again before downstream publication. Upstream _meta is consumed locally; typed serialization cannot inject replacement metadata. The gateway reconstructs correlation for the downstream request, using its owned SSE stream for HTTP or its own request ID for memory and stdio. A request without an output sink is refused before any upstream request is started.

All intermediate events share a 64-event budget. Core progress and log events count toward the budget and are consumed without being relayed. Downstream framework metadata is not application payload or an upstream activation proof. Cancelling or dropping a forwarded request closes its owned upstream execution while sibling requests continue independently.

Standalone client-to-server notifications use ExtensionBuilder::typed_http_proxy_notification::<Notification, _>. Register the same notification method, schema identity, and activation-metadata key on both legs, supply an explicit typed authorization policy, and pass the independently connected ExtensionHttpUpstream. Request and notification routes may share one upstream when their complete contracts match.

Each notification consumes its own downstream activation proof and the exact payload admitted by its authorization policy. The gateway checks typed serialization and effective-settings equality, then sends a fresh upstream notification with the upstream client's own proof and credentials. A change in the upstream resolver's effective settings is rejected before sending. Only an empty HTTP 202 acknowledges completion. The upstream handle admits at most 64 concurrent notification POSTs across its clones; completion, cancellation, or Drop releases the permit. Notifications allocate no request ID or response waiter and are never retried automatically.

Typed extension gateways to stdio subprocesses (Unix)

With extension-authoring and proxy enabled, the same typed extension contracts can forward to a local subprocess. Consume the upstream declaration with modern::ClientBuilder::connect_extension_stdio_upstream_with_cx, supplying the caller's cx, executable, arguments, and typed client settings. Discovery and settings negotiation finish before it returns an ExtensionStdioUpstream, including when the builder defers ordinary initialization.

Install the complete matching contract on the gateway with typed_stdio_proxy_request::<Request, Response>. For request-owned server notifications, declare the event and use typed_stdio_proxy_request_with_notifications::<Request, Response, Notification>. Standalone client notifications use typed_stdio_proxy_notification with an explicit typed authorization policy. Both legs independently negotiate; contract identities, schemas, and effective settings must match. Framework metadata is rebuilt for the upstream leg, and request-owned notification IDs are rewritten for the downstream request.

Cloned upstream handles share one subprocess and one bounded ingress driver. Requests have independent IDs, cancellation, deadlines, and a 64-event intermediate-notification bound. Cancelling or dropping a forwarded call publishes its retirement even when no sibling request is driving the child. Standalone notifications allocate no request IDs; success means publication to the pipe. The adapter does not create a detached task or private runtime, and its receive turns retain the native client's bounded synchronous slices. After dropping installed routes and other handles, consume the last handle with close_with_cx to await observable subprocess cleanup.

Typed extension gateways to WebSocket upstreams

Enable extension-authoring, proxy, and websocket-experimental. The caller supplies an owned AsyncWsClientTransport, acquired with connect, connect_wss, or its own Upgrade/TLS setup. Reusing the typed echo declaration above:

let upstream = modern::ClientBuilder::new()
    .connect_extension_websocket_upstream_with_cx(
        cx,
        transport,
        EchoExtension.register(make_builder()?)?.build()?,
        &Settings {},
    )
    .await?;
let registration = make_builder()?
    .typed_websocket_proxy_request::<Message, Message, _>(
        "com.example/echo",
        "echo-params-v1",
        "echo-result-v1",
        upstream.clone(),
    )?
    .build()?;

Install registration on the gateway as above. Both legs independently negotiate the complete contract; schema identities and effective settings must match. The adapter validates typed payloads and creates fresh upstream IDs and metadata. Cloned handles share one connection and admit at most 64 running or waiting operations on the caller's runtime.

Awaited cancellation settles native request retirement before connection reuse. Dropped requests retain cleanup ownership for the next operation or close. After serving finishes, call upstream.close(cx).await?; retain the handle to retry an acquisition failure. Idle cleanup accepts a cancelled caller; busy cleanup requires the caller's timer and has a finite acquisition bound.

Standalone client notifications use typed_websocket_proxy_notification::<Notification, _, _> with an explicit authorization policy and the same complete declaration. They receive fresh activation proof, allocate no request ID, and are never retried automatically. This adapter supports finite request/results and standalone client notifications; request-owned server notifications, Tasks, and subscription relays remain outside its supported contract.

In-process test clients

Enable the facade's testing feature to use testing::TestClient with a caller-owned Cx and MemoryTransport. TestClient::new_modern selects exact MCP 2026-07-28; new retains the exact-2024 helper when that protocol feature is enabled. These helpers do not create a runtime. Synchronous requests require the peer to be driven independently.

Use initialize_core() to retain the complete modern discovery, including its optional identity, cache contract, and open members. request_core(method, params) returns the full typed method result with its original JSON number lexemes and modern input_required state. Legacy-shaped convenience helpers report an input-required result as an error directing the caller to that typed API. Invalid discovery, malformed results, and mismatched response IDs retire the endpoint. Valid peer errors preserve their data and leave it usable.

For concurrent requests, reverse interactions, subscriptions, or explicitly configured Tasks, consume an unused helper with connect_modern().await or connect_modern_with(configure).await. These transfer the existing endpoint and caller context to the shipped asynchronous MemoryClient; connect_modern_with exposes its normal builder for reverse handlers and extension settings. The resulting client owns normal request cancellation and terminal results, and the server can run on the same caller runtime. No blocking pool or deterministic test runtime is required for Memory I/O.

new_auto only retries after an admitted, correlated modern MethodNotFound. Install with_legacy_transport_factory to supply a fresh, independently driven endpoint for that one exact-2024 attempt. The modern probe is closed before the factory runs. Without the factory, the error is returned; the probe endpoint is never reused for a different protocol era.

Client executor observations

OperatorExecutorSnapshot captures the selected protocol profile, lifecycle, structural readiness, and the capacity actually charged by a client executor. It is available from RequestExecutor, a retained StdioRequestExecutor handle, and MemoryClient:

use fastmcp_rust::{
    OperatorExecutorCapacity, OperatorExecutorSnapshot,
    OperatorSnapshotError, OperatorSnapshotSource,
};

fn observe(
    client: &(impl OperatorSnapshotSource<OperatorExecutorCapacity> + ?Sized),
) -> Result<OperatorExecutorSnapshot, OperatorSnapshotError> {
    OperatorExecutorSnapshot::capture(client)
}

A snapshot's requests() counts pending requests and deferred transport controls. Its correlations() counts pending requests, retained tombstones, and unconsumed terminal outcomes. These use the same charge arithmetic as request admission. Capturing a snapshot never sends a message, reads the transport, reserves a slot, or performs expiry maintenance. If an executor turn currently holds its state lock, capture returns OperatorSnapshotError::Busy immediately.

Ready describes structural admission; the capacity gauges can simultaneously report saturation. Ordinary service turns release expired and abandoned-owner charges. The snapshot includes no request IDs, peer data, credentials, endpoint addresses, or error text. Retained handles keep their configuration generation after shutdown and distinguish an intentional stop from a real connection failure, including a failure followed by successful cleanup.

HTTP listeners retain their existing OperatorSnapshot connection-admission surface. These client observations cover the executor-backed stdio and memory paths; they do not imply readiness of other client transports, durable task workers, credentials, or the entire application.

Tasks store observations

With tasks enabled, FinalTaskRuntime::task_operator_handle() returns an optional TaskOperatorHandle for the installed store. The built-in InMemoryFinalTaskStore supplies this handle; custom stores may omit it. Capture it through the same exporter-neutral API:

use fastmcp_rust::{OperatorTaskSnapshot, OperatorSnapshotError, TaskOperatorHandle};

fn observe_tasks(
    handle: &TaskOperatorHandle,
) -> Result<OperatorTaskSnapshot, OperatorSnapshotError> {
    OperatorTaskSnapshot::capture(handle)
}

The observation includes retained task states, storage counts and encoded-byte charges, reserved retirement capacity, active execution capacity, and retention journal usage. These gauges come from the store's actual admission accounting. Terminal results continue to consume storage until normal expiry or authorized reclamation; an execution permit remains charged while its service future is still cleaning up. The snapshot exposes aggregate pressure without task IDs, principal identities, input values, results, or error messages.

Capture uses immediate lock attempts and returns Busy when a store mutation owns the necessary state. It does not scan task payloads, run expiry maintenance, invoke application clocks or providers, or reserve capacity. A retained handle does not keep a discarded store alive. The HTTP readiness response includes the optional Tasks observation when available, while connection readiness continues to describe HTTP admission: a full Tasks store does not prevent ordinary tool, resource, or catalog requests from using available connections. This is process-local operational visibility, not persistent Tasks or an application-wide readiness guarantee.


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
Crate Purpose
fastmcp-rust Convenience re-exports for simple use fastmcp_rust::prelude::*
fastmcp-core McpContext wrapper, error types, block_on helper
fastmcp-protocol MCP message types, capabilities, JSON-RPC framing
fastmcp-transport Transport trait and stdio/SSE/WebSocket/HTTP/memory implementations
fastmcp-server Server, ServerBuilder, routing, handler traits
fastmcp-client Three clients: Client drives a subprocess over stdio; HttpClient covers modern HTTP and exact legacy SSE and is returned by Client::http_with_cx and (with legacy-2024-11-05) Client::sse_with_cx, with ClientHttpConnection beneath it; WebSocketClient exists only with the websocket-experimental feature, where it accepts owned native async transports and Auto negotiation uses a caller-owned factory that supplies a fresh upgraded transport for its permitted retry
fastmcp-derive Procedural macros for handler generation

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

Problem Cause Fix
JSON-RPC InvalidParams (-32602) Unknown tool: <name> for tools/call Tool not registered Register the generated handler, for example .tool(MyTool)
Request cancelled mid-operation Local request cancellation or budget exhaustion Add checkpoints and mask only the smallest atomic section that must finish; Unix stdio and native WebSocket connections keep receiving while bounded modern request children run, but output commits are serialized, non-Unix/custom/SSE loops retain blocking boundaries, and a non-cooperative handler can exceed the process-exit quiescence drain
JSON-RPC RequestCancelled (-32004) error Request timeout exceeded The request outlived the server-owned deadline (.request_timeout(...), 30 seconds by default), whether the server or the handler's own checkpoint observed it first Add checkpoints so work stops promptly; increase .request_timeout(...) only for a deadline that is intentionally too short
#[tool] macro compilation error Unsupported return conversion or argument schema Prefer String, Vec<Content>, McpResult<String>, or McpResult<Vec<Content>> and ensure custom argument types implement JsonSchema
TransportError::Io on startup stdin unavailable Ensure nothing else reads stdin

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

Limitation Details
Pinned Nightly Required The project contract pins nightly-2026-08-25; do not substitute a different toolchain merely because it supports Edition 2024
Protocol Modernization The root compatibility PROTOCOL_VERSION remains 2024-11-05; the modern facade's modern::PROTOCOL_VERSION is 2026-07-28. MCP 2026-07-28 implementation and verification are incomplete
Poll-quota accounting is scoped to framework operations McpContext::checkpoint keeps a clone-shared request debit counter. The synchronous client RequestExecutor also consumes a finite poll budget during execute, drive, and wait, sharing it across nested control maintenance and every frame of a wait. Exhausting this local ledger stops that call without cancelling the caller's shared Cx or unrelated request owners. This operation-admission limit also applies inside Cx::masked; runtime cancellation and deadline delivery retain the original mask semantics. An already exhausted raw budget retains the runtime's existing cancellation behavior. Separate executor calls start separate budget snapshots; this is not a global quota across calls or a bound inside an arbitrary blocking transport. Other APIs that checkpoint only a raw Cx still reject an already exhausted quota without consuming a positive one: asupersync 0.6.2 exposes that budget as a read-only Copy snapshot. Deadline and explicit cancellation remain effective at their documented boundaries
Runtime-context migration Library client constructors and returning/custom transport runners require a caller-owned Cx. The process-owning CLI and Server::run_stdio_with_cx install the ambient context at their top-level runtime boundary; test-internals is confined to test-only dependencies and the facade's opt-in testing-lab feature
Network Transports The turnkey run_http* entry points provide a caller-owned dual-era HTTP listener and dispatch lifecycle. The experimental websocket-experimental facade profile provides native async bind_websocket and serve_websocket listener and connection lifecycles for Auto, ModernOnly, and exact-2024 LegacyOnly, plus caller-driven client connection. Every server policy retains the accepted Upgrade authentication, configured request limits, and caller authority; Auto binds each connection to one protocol era. These surfaces do not establish aggregate conformance or complete lifecycle qualification
Client Transport Coverage The fastmcp-client::Client type drives a subprocess over stdio. Its Client::http_with_cx and (exact-2024) Client::sse_with_cx constructors return a separate HttpClient, and WebSocketClient requires websocket-experimental. Public ClientHttpConnection and HttpClient provide modern HTTP and exact legacy SSE integration with typed list_tools/call_tool/read_resource/get_prompt verbs. Modern HTTP answers typed reverse sampling/createMessage, roots/list, and elicitation/create requests that arrive on a request-owned SSE body by POSTing the JSON-RPC response. Public HttpClient::call_tool and WebSocketClient::call_tool also follow modern server input_required by invoking those same installed handlers locally and retrying with inputResponses. Live bind_http JSON tools/call returns ctx.final_sampling and ctx.final_roots as input_required; a write-half EOF after the request is ordinary H1 completion and does not cancel that result. Public modern::Client stdio call_tool_result / read_resource_result / get_prompt_result keep the same live input_required branch. A Modern2026 stdio session stamps the same _meta protocol version and client capabilities on start_multiplexed_request that the typed verbs already send. Public stdio read_resource / get_prompt follow installed modern reverse handlers the same way call_tool does. Eligible stateless HTTP MRTR retries use framework-issued opaque, single-use requestState and may resume on a later POST only when the method, target, arguments, and admitted principal still match; forged or replayed state is rejected. Elicitation resumes the same way: the client's answer travels in inputResponses on the retry POST, bound to the original request by that single-use state. With websocket-experimental, the facade exposes WebSocketClient with incremental catalog listen, the same typed verbs, and the same modern reverse handlers: ModernOnly and LegacyOnly builders accept an owned async WebSocket transport, while Auto accepts a caller-owned factory that yields a fresh upgraded transport for initial modern discovery and its sole permitted exact-2024 retry
Two modules ship with tests but no consumer fastmcp_transport::event_store (TTL retention, per-stream caps, replay_bounded cursor paging, 45 tests) has no consumer anywhere: its only references are its own pub mod declaration and the facade re-export. SSE resumption is deliberately not wired — exact 2024-11-05 reconnects start a fresh stream and Last-Event-ID is intentionally ignored, pinned by dual_era_endpoint_ignores_last_event_id_and_starts_a_fresh_legacy_stream. fastmcp_transport::http::HttpTransport is a complete synchronous HTTP/1.1 Read/Write adapter (request-line and token validation, obs-fold and duplicate-Host rejection, Content-Length/Transfer-Encoding conflict rejection, chunked decoding, 183 tests); the live listener does not use it, reaching the wire through asupersync::http::h1::Http1Codec instead, and its only out-of-crate consumer is one #[cfg(test)] fixture in fastmcp-server. Neither is an overclaim — this README promises no SSE replay — but 228 green tests exercise code no shipped request path reaches, so treat them as unclaimed library surface rather than as coverage of the HTTP or SSE paths
Experimental WebSocket framing The frame codec that ships is asupersync's. fastmcp_transport::websocket compiles unconditionally, but its own RFC 6455 implementation — WsFrame, WsReader::read_frame, WsWriter::write_frame, WsClientWriter, generate_mask, EndpointRole::validate_peer_mask, WsTransport/WsClientTransport and their Transport impls — is #[cfg(test)] and is in no release binary. getrandom's WebSocket-masking use is likewise test-only. The shipping path (AsyncWsClientTransport, AsyncWsServerTransport, WebSocketListener, WebSocketUpgradeAdmission) uses asupersync::net::websocket for handshake and framing; FastMCP owns fragmentation assembly, opcode dispatch, size ceilings, pending-write bounds and close-code selection above it. Those production transports implement no Transport impl, unlike AsyncStdioTransport. Consequently any RFC 6455 invariant proven only against the cfg(test) codec — mask direction in particular — is not evidence about the shipped path
Experimental WebSocket TLS The experimental async transport supports ws:// and wss://. wss:// can use the built-in WebPKI-rooted connector or a caller-supplied TLS connector for private roots, pinning, or client certificates; this connection support does not imply complete TLS, lifecycle, or MCP conformance qualification
HTTP Dispatch Qualification Public run_http* binds and serves the caller-owned dual-era HTTP lifecycle. ModernOnly selects the exact MCP 2026-07-28 era and LegacyOnly selects the exact MCP 2024-11-05 era; MCP 2025-11-25 is not an adapter or supported policy. This executable surface does not establish aggregate MCP conformance or complete lifecycle qualification
Wire Cancellation The modern-only split receive pump, including Unix stdio, admits bounded concurrent requests on the caller's dispatch runtime, including subscriptions/listen. It authenticates cancellation against the existing connection owner and serializes cancellation, response, and notification commits at the writer. Synchronous split runners use the bounded asupersync blocking bridge. Unsplit custom transports dispatch ordinary requests serially because receive and send share one handle; a subscriptions/listen runs off the receive loop, and output produced while recv blocks is queued and written as soon as recv returns. Transport reads and writes can still block. The dual-era Unix stdio pump retains its concurrent modern children and serialized exact MCP 2024-11-05 worker. A non-cooperative handler can exceed the bounded process-exit drain, and reliable awaitCleanup semantics remain unverified. "Transport reads and writes can still block" is a statement about the blocking stdio and custom adapters; a Unix serve_stdio_io server over the native process pipes does not block in its reader or writer, which removes that one residual without establishing any of the others
Silent stdio peers On Unix, the public subprocess Client enforces configured idle/absolute deadlines at child-pipe readiness and decode boundaries, including silent and partial-frame peers. Generic blocking StdioTransport::recv and non-Unix child-pipe I/O retain their documented frame/I/O-boundary limitation. Unix client writes use a separate two-second queue-and-commit deadline, so response-wait deadlines are not an end-to-end request or process wall-clock guarantee. Those residuals remain FND-04 work
Stdio output backpressure On Unix, primary server responses and notifications use serialized nonblocking writes with a two-second commit deadline for ordinary pipes/sockets; a timeout, lock poison, partial write, notification encoding failure, or descriptor-flag restoration failure is connection-fatal. The writer attempts to restore descriptor flags before releasing the local lock; on restoration failure the descriptor may remain nonblocking, and inherited duplicate descriptors can observe the temporary O_NONBLOCK setting. Regular files/devices and non-Unix stdout retain blocking-I/O limits. A handler that ignores cancellation may force unsuccessful process exit after the bounded drain; shutdown hooks are skipped unless all worker and modern-child quiescence is proven. This row describes the run_stdio_with_cx writer; a serve_stdio_io server over NativePipeWriter commits through the asynchronous transport instead, which has its own separate boundaries (see Non-blocking stdio)
Subprocess cleanup Client::close(&mut self) -> McpResult<()> is the proof-bearing path; Drop is best effort. fastmcp test uses Unix-only anchored process-group ownership; successful connections report explicit final cleanup separately, and initialization-cleanup failures remain visible. Descendants can escape via a new group/session, host forks can copy the control descriptor, and SIGCHLD=SIG_IGN, SA_NOCLDWAIT, or competing global reapers can invalidate reap evidence. Windows Job Object support is not implemented
Development subprocess cleanup On Unix, each fastmcp dev build/server group contains a signal-immune watchdog tied to a private owner-held control pipe, so ordinary shutdown, child-handle drop, and CLI owner death trigger bounded TERM-then-KILL cleanup. A host-side fork that copies the owner descriptor or a descendant that changes group/session remains outside this boundary; non-Unix dev remains fail-closed
CLI --output atomic publication On Unix (Linux and macOS), fastmcp inspect -o/--output <PATH> stages to a sibling temporary file, refuses symbolic links and .. parent traversal, and publishes atomically without clobbering existing files on upstream failure. Non-Unix targets fail closed until atomic no-symlink publication is verified there
Synchronous HTTP readers Low-level HTTP parsing checkpoints before/after reads and retries EINTR, but a generic synchronous Read already blocked in the kernel cannot be preempted. A bounded host must supply readiness-aware/asynchronous I/O. Public turnkey run_http* uses its caller-owned asynchronous listener lifecycle, whose broader qualification boundaries remain documented here
Returning transport runners run_transport_returning_with_cx and the split returning variants return fatal receive/send/close errors and preserve simultaneous run-plus-close failures. Clean EOF/cancellation is Ok(()). Each exact-2024 handler dispatch now opens and closes a budgeted child region of the caller's runtime, requiring a runtime-backed Cx. Blocking transport I/O and complete cancellation/cleanup guarantees remain unresolved
Request Cancellation Ownership Unix modern stdio request work runs in independently owned bounded child contexts, but process-exiting shutdown does not wait unboundedly for a non-cooperative child; cancellation therefore is not yet a complete quiescence or awaitCleanup guarantee
Bidirectional Response Routing On Unix, stdio continuously routes inbound responses while exact-2024 lifecycle work or modern request children are active. Native WebSocket connections preserve this routing for every policy, including exact-2024 reverse sampling, roots, and owner-authenticated cancellation while serialized handler work awaits. Custom split transports retain their synchronous routing pump. Non-Unix stdio, unsplit custom transports, and SSE do not provide the same split routing. Public HTTP has separate dual-era routing, while end-to-end bidirectional lifecycle qualification remains open
Response Cache Partitioning Eligible entries are partitioned by committed authentication facts and opaque session identity/revision; ambiguous admission and state mutation fail closed. This does not promote OAuth/OIDC or establish protocol conformance
Authentication Admission Native HTTP requires Authorization for protected requests and rejects recognized body/meta and query credential fields before provider invocation. Other adapters retain a stripped legacy fallback. Complete authorization, lease/revocation, and OAuth challenge qualification remain open
Tasks RPC tasks/list and tasks/submit stay MethodNotFound. Official tasks/get, tasks/update, and tasks/cancel run by default on a process-local in-memory store; ServerBuilder::final_tasks replaces that store. ServerBuilder::task_supervisor(Arc::new(supervisor)) hosts the application's task service during each serve, waits for bounded readiness, and settles the service before returning. Without a ready service, task creation is refused
MCP Apps (opt-in apps feature) Off by default. The facade apps feature adds the official MCP Apps extension: server ServerBuilder::mcp_apps (bilateral capability negotiation and server/discover metadata; Apps owns no client-to-server method), mcp_apps_ui_resource for final-only ui:// HTML documents and mcp_apps_tool for tools linked to one; client ClientBuilder::mcp_apps and the mcp_apps host bridge (McpAppsHost, McpAppsBridgeTransport). These are unit-tested (for example builder_mcp_apps_ui_resource_binds_a_final_only_ui_catalog_entry); Apps media rendering and Apps conformance are not claimed
Feature flags that gate nothing fastmcp-server's enterprise-auth now gates auth::enterprise and enables jwt-resource-auth; the facade enables both the client exchange and resource-server policy. Its jwt-resource-auth does gate code and this row claimed the opposite until 2026-10-20: since 2026-10-14 it gates providers::jwt_resource and providers::managed_jwks (3,735 lines and 45 tests as of 2026-11-20) implementing two TokenVerifiers that install through the ordinary TokenAuthProvider hook, so an inbound-JWT resource-server path does exist for it to reach. A consumer reaches them as fastmcp_rust::providers::JwtResourceVerifier once the facade's own jwt-resource-auth equation — added 2026-10-20, because until then the published facade declared no such feature and Cargo refused to resolve it — is enabled. fastmcp-server's websocket-experimental is also inert: it forwards only to fastmcp-transport's empty feature and is a different feature from fastmcp-server/websocket, which does gate code. The CLI's jwt-resource-auth forwards to the server feature above and carries dep:fastmcp-server, linking the server crate into the CLI. fastmcp-console's enterprise-auth, oauth-client-credentials, builtin-auth-server, jwt-resource-auth, proxy and websocket-experimental are empty, so its proxy-legacy and proxy-tasks reduce to legacy-2024-11-05 and tasks. fastmcp-transport's websocket-experimental is empty because fastmcp_transport::websocket is compiled unconditionally — but see Experimental WebSocket framing below: the always-compiled frame codec is not the one that ships. By contrast fastmcp-server's oauth-client-credentials is not inert: together with builtin-auth-server it gates 34 sites, including the client_credentials arm of the token endpoint and the advertised grant_types_supported list. The facade and client websocket-experimental features gate code: WebSocketClient, ClientBuilder::connect_websocket_with_cx, and (through fastmcp-server/websocket) bind_websocket. This list is complete as measured 2026-11-05 over every declared feature in the nine crates that declare any (fastmcp-core declares exactly one, test-runtime, added 2026-11-02 by 0035bc4d; it is not inert, carrying eight cfg(feature = "test-runtime") sites): the seven user-enableable features with zero cfg(feature = ...) sites in their own crate's src and an empty value list are exactly fastmcp-console's six above plus fastmcp-transport's websocket-experimental
HTTP as_proxy auto-follow A gateway HTTP as_proxy does not auto-follow an upstream server input_required task across POSTs; per-request dispatch is stateless and upstream request state cannot resume. Callers resume such upstream tasks through an explicit matching tasks/update
OAuth/OIDC Promotion Public source APIs exist, but production security and profile conformance remain unverified; they are quarantined from production-support claims
Early Development API may change before 1.0

MCP Apps host sampling

With the apps feature, a negotiated McpAppsWireHost accepts the View's standard sampling/createMessage request when its committed ui/initialize response advertises hostCapabilities.sampling. Supply the model operation through McpAppsWireHostEffects::sampling_create_message and attach the effects with host.with_effects(effects). The public facade exports McpAppsSamplingCapability, McpAppsSamplingParams, and McpAppsSamplingResult at the root and under modern.

The callback owns approval for each invocation, model selection, any requested context inclusion, and consent to disclose the result to that View. Its default refuses the request. Advertising sampling: {} permits plain sampling; sampling: { tools: {} } additionally permits the tools and toolChoice parameters. Tool descriptions grant no permission to execute those tools. The request runs under the caller's context with a bounded deadline; matching View cancellation drops its pending work and suppresses its response.

Sampling uses the isolated Apps JSON-RPC channel and never forwards a standalone sampling request to the MCP server. Plain requests return one text, image, or audio block; requests carrying tools may return extended sampling content. Results are validated against the original request before disclosure, preserve the View's request ID, and carry no modern MCP resultType. This is a browser-neutral Host capability: the embedder still supplies its model provider and rendering environment.

MCP Apps Task cancellation and input lifetime

With apps and tasks, a Host can override McpAppsWireHostEffects::approve_server_task_cancellation to authorize one remote tasks/cancel when a matching View cancellation stops observation of an approved, nonterminal server Task. The default returns false, so existing Hosts retain local-only cancellation. The synchronous hook checks the current View, origin, principal and consent policy; ordinary cancellation observers run first. When effects are composed, only the most recently installed effects can grant remote cancellation.

The framework supplies the original View parameters and the last approved Task snapshot to that hook. It obtains the Task ID from the authenticated MCP peer, never from the View's cancellation frame. HTTP, Unix stdio, WebSocket and Memory use their existing typed Task methods, including the independently negotiated tasks/cancel permission, a fresh MCP request ID, and the original caller's authority. The grant expires within five seconds and cannot extend the original request deadline. Native transport cleanup retires the abandoned observation before dispatch where necessary.

An authorized cancellation is attempted once. Losing its response or dropping cleanup does not replay the mutation; acknowledgement does not establish that the Task has reached a terminal state. Arbitrary future drop, timeout and View disconnect do not grant cancellation. Denial or an approval-hook error leaves cancellation local. A failure during authorized native cleanup closes that View through the existing transport-failure path.

For input_required Tasks, the Host checks retention before invoking consent, sampling or elicitation effects. A finite remaining lifetime shortens the operation's monotonic deadline, including pending Host callbacks and subsequent updates or reads. An expired snapshot cannot disclose input to a Host callback, and later wall-clock rollback cannot extend an already admitted deadline.


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: #[tool] keeps your function, so call it directly with an McpContext built from a runtime's context and a request ID. (Cx::for_testing() needs asupersync's test-internals feature; this form needs no extra features.)

use asupersync::runtime::RuntimeBuilder;
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 runtime = RuntimeBuilder::current_thread()
        .build()
        .expect("create test runtime");
    runtime.block_on(async {
        let ctx = McpContext::new(Cx::current().expect("test context"), 1);
        let result = my_tool(&ctx, "input".to_string());
        assert_eq!(result.unwrap(), "input");
    });
}

Verifying a Checkout

From a committed checkout, use the repository's DSR entrypoint. It supplies identical fastmcp and fastmcp_rust registrations, runs compilation and tests through RCH, and retains the commands, source revision, logs, and test IDs. Python 3.11 or newer, DSR, and RCH must be available on PATH.

# Compile every workspace target with every feature enabled.
scripts/verify_batch.sh --scope '--workspace --all-targets' --all-features --check-only

# Exercise the facade library, including the real Memory test-server helpers.
scripts/verify_batch.sh --scope '-p fastmcp-rust --lib' --features testing-lab

# Check the installed DSR contract without compiling Rust.
scripts/verify_batch.sh --self-test-dsr-contract

Test runs require the selected targets' features and compare discovered, started, and passed tests exactly. Empty or incomplete runs fail. A successful run proves its recorded scope only; aggregate MCP conformance remains unverified.


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.