Core Concepts

FastRMCP primitives you will touch in every server. See Tools/Resources/Prompts for macro details.

Context

Injected via Context parameter (optional) into tools/resources/prompts.
Carries server_info, optional client_info, request_id, metadata map, and a notification sender.
Progress + logs: ctx.report_progress(progress, total, Some("msg")) and ctx.log_info(...) emit MCP notifications; falls back to tracing if no transport hook.
Metadata: ctx.set_metadata("key", json!(value)).await and ctx.get_metadata("key").await for middleware/handler sharing. Avoid blocking on metadata inside tight loops.
ID helper: Context::generate_id() for unique tokens.

Type-safe shared container (fastrmcp::state::State) stored on FastMCP and clonable.
Insert at startup: .with_state(|state| state.insert(DatabasePool::new()).unwrap()).
Access inside handlers by adding State param and state.get::<T>()? returning Arc<T>.
Lifetime nuance: get() returns Arc clones that remain valid even after remove()/clear()—plan for that if you hot-swap state.

Auto-registration via inventory for #[tool], #[resource], #[prompt].
Tool/Prompt registries validate uniqueness; Resource registry also validates URI template collisions.
Required order: FastMCP sets server_info before register_from_inventory so #[resource] fallback contexts have server metadata—don’t bypass FastMCP::new(...).run() with manual registration unless you call resource_registry.set_server_info(...) first; otherwise resources will error with “Server info not set before resource registration.”
Lookup helpers: server.tool_registry().list(), .get(name), same for resources/prompts.

#[on_startup] and #[on_shutdown] macros register async hooks run before the main loop and during graceful shutdown.
Best for initializing stateful services, warming caches, or flushing telemetry.
Hooks run sequentially; return Result<()> to fail fast on critical setup errors.

Built-in SubscriptionManager exposed from the handler; resources are subscribable out of the box when using #[resource].
Protocol methods: resources/subscribe, resources/unsubscribe, resources/list_subscriptions.
Notifications flow through transports; see Subscriptions & Notifications and Transports Guide for connectionId handling.

Primary error: fastrmcp_core::error::MCPError with JSON-RPC-friendly codes.
Common variants: InvalidParams, MethodNotFound, ResourceNotFound, PromptNotFound, TransportError, Custom { code, message, data }.
Return Result<T> (alias to Result<T, MCPError>) from handlers; convert IO/serde errors via ? (From implementations map to TransportError/ParseError/SerializationError).
For validation, prefer InvalidParams so clients get actionable feedback; use ServerError with specific codes (-32099..-32000) for server-specific faults.