Related Pages

Related topics: Server Core: Tools, Resources, Prompts, and Middleware, Authentication, Providers, and Proxy

Overview and Core Architecture

Purpose and Scope

FastMCP is a Python framework for building and interacting with servers that implement the Model Context Protocol (MCP). The project positions itself as "the standard way to build MCP servers," wrapping ordinary Python functions into the three MCP primitives — tools, resources, and prompts — that LLM clients can discover and invoke. Source: README.md.

The repository delivers three primary product surfaces, as stated in the README:

Source: README.md.

The shipped package, fastmcp_slim, is the published distribution; it exposes a parallel layout under fastmcp_slim/fastmcp/. Source: fastmcp_slim/README.md.

Core Architecture Components

flowchart LR
    User[Developer] --> CLI[fastmcp CLI]
    CLI --> Run["cli/run.py<br/>fastmcp run / install"]
    CLI --> Cursor["cli/install/cursor.py"]
    CLI --> Gemini["cli/install/gemini_cli.py"]
    Run --> Server[FastMCP Server]
    Server --> Auth[Auth Providers]
    Server --> Contrib["Contrib modules<br/>(component_manager, mcp_mixin)"]
    Server --> Apps[MCP Apps Layer]
    Server --> Proxy[StatefulProxyClient / FastMCPProxy]
    Client[FastMCP Client] -- mixins --> ToolsM["client/mixins/tools.py"]
    Client -- mixins --> ResM["client/mixins/resources.py"]
    Client --> OAuth["client/oauth_callback.py"]
    ToolsM --> Server
    ResM --> Server
    OAuth --> Auth

Server Layer and the Provider/Component Model

The server is built around a FastMCP class that owns *providers* — pluggable component stores that hold tools, resources, and prompts. Servers can be aggregated so multiple providers coexist, letting developers compose mounts and proxies rather than flatten everything into a single registry. Source: README.md.

The server also performs protocol-level duties: MCP operation dispatch (list/call/read for tools and resources), authentication enforcement, middleware execution, and per-session lifecycle handling. The release notes for v3.4.2 highlight that JWT validation now tolerates non-critical private JWS header parameters while still rejecting unsupported *critical* headers — a server-side concern handled in the auth providers. Source: fastmcp_slim/fastmcp/server/auth/providers/jwt.py.

Client Layer and Mixin Architecture

The client is composed through mixins so that each MCP primitive has its own self-contained API. ClientToolsMixin exposes tool listing, invocation, and async task polling (AUTO_PAGINATION_MAX_PAGES = 250 guards pagination loops), while ClientResourcesMixin mirrors that for resources. Source: fastmcp_slim/fastmcp/client/mixins/tools.py, fastmcp_slim/fastmcp/client/mixins/resources.py.

The OAuth callback flow uses dataclasses (CallbackResponse, OAuthCallbackResult) plus an anyio.Event for async coordination between the local HTTP listener and the client transport. Source: fastmcp_slim/fastmcp/client/oauth_callback.py.

Authentication Subsystem

Authentication is pluggable through TokenVerifier subclasses. Two concrete providers illustrate the range:

• DebugTokenVerifier — accepts tokens via a user-supplied sync or async validate callable. The async branch is detected with inspect.iscoroutinefunction. Source: fastmcp_slim/fastmcp/server/auth/providers/debug.py.
• JWTVerifier — uses joserfc and cryptography, supports HMAC (HS*), RSA/PSS (RS*/PS*), and EC (ES*) algorithms, and resolves JWKs from a remote JWKS endpoint guarded by ssrf_safe_fetch. Source: fastmcp_slim/fastmcp/server/auth/providers/jwt.py.

CLI, Installation, and Runtime Entry Points

The CLI lives under fastmcp/cli/ and is split between run logic and install adapters. cli/run.py recognizes file extensions (Python, JSON, YAML, TOML, GraphQL, images, media, fonts) and can spawn a server from a file spec, an MCPConfig, or a URL by wrapping a Client in create_proxy. Source: fastmcp_slim/fastmcp/cli/run.py.

The install adapters write platform-specific MCP configuration so editors and assistants can launch the server. install_cursor.py updates the workspace-scoped mcp.json (StdioMCPServer with command, args, env), while install_gemini_cli.py shells out to gemini mcp add with environment variables injected via -e. Both functions follow the same pattern: build a server spec (file.py:object), construct a launch command, and merge it into the host's config file. Source: fastmcp_slim/fastmcp/cli/install/cursor.py, fastmcp_slim/fastmcp/cli/install/gemini_cli.py.

Contrib and Examples

The contrib/ namespace is for community-maintained modules with relaxed stability guarantees — they may have separate dependencies and testing requirements. Source: fastmcp_slim/fastmcp/contrib/README.md. Two prominent examples:

• component_manager — adds HTTP endpoints (POST /tools/{name}/enable, /disable, plus the same for resources and prompts) for runtime enable/disable, with optional auth scopes. Source: fastmcp_slim/fastmcp/contrib/component_manager/README.md.
• mcp_mixin — MCPMixin base class plus @mcp_tool, @mcp_resource, @mcp_prompt decorators with support for tool annotations, excluded arguments, and metadata. Source: fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md.

The fastmcp.json configuration file is the canonical project descriptor — it carries an entrypoint, optional environment, and optional deployment blocks. Source: examples/fastmcp_config_demo/README.md.

Known Architectural Concerns from the Community

Several recurring issues reveal where the architecture is still evolving:

• Server-wide tool timeout defaults — Timeouts are per-tool (@tool(timeout=...)), forcing boilerplate across large servers. Community request #4304 asks for FastMCP(default_tool_timeout=...). Issue #4305 also asks for hooks to customize timeout error messages and exception types, since current behavior is hardcoded (MCP error code -32000).
• Middleware coverage — Caching middleware breaks on context= argument mismatches (#4300), RateLimitingMiddleware.get_client_id silently fails when an async callable is passed because its type is sync-only (#4320), and on_message middleware does not fire for requests rejected by auth (#4309).
• Proxy lifecycle — StatefulProxyClient.clear() can raise KeyError during session teardown when FastMCPProxy.new_stateful() registers an _on_session_exit callback that races with cache invalidation (#4321).
• OAuth gaps — CIMD redirect_uri validation rejects loopback URIs that omit an explicit port even though RFC 8252 §7.3 permits dynamic ports (#3588). Full OAuth 2.1 support (#825), Keycloak with Dynamic Client Registration (#1918), and multi-tenant routing in OAuthProxy (#1802) are open requests.
• URI template encoding — expand_uri_template does raw replacement and match_uri_template requires [^/]+, so reserved characters in path values do not round-trip cleanly (#4326).
• Schema recursion — json_schema_to_type raises RecursionError on self-referential $ref entries in a tool outputSchema, breaking client-side type construction (#4306).
• Developer ergonomics — Hot-reload (--reload) has been requested since #616, and #4318 calls for capability declarations so tools that execute shell commands or delete files are surfaced to clients.

These items do not change the documented architecture, but they describe the seams where the framework is still hardening before its 4.x trajectory.

See Also

• Servers documentation
• Clients documentation
• Apps overview
• Installation guide
• Quickstart
• Component Manager (contrib)
• MCP Mixin (contrib)

Related Pages

Related topics: Overview and Core Architecture, Authentication, Providers, and Proxy, Clients, Apps, Tasks, and Extensibility

Server Core: Tools, Resources, Prompts, and Middleware

Overview

The FastMCP server core exposes a unified model for authoring and exposing MCP primitives — tools, resources, and prompts — and for observing or transforming inbound requests through middleware. Developers register components declaratively via decorators, and the LocalProvider resolves them into the underlying MCP server object model. This page describes the structure and behavior of that core surface.

flowchart LR
    Dev[Developer] -->|@tool / @resource / @prompt| Decorators
    Decorators -->|FunctionTool / etc.| LocalProvider
    LocalProvider -->|registers| FastMCP[FastMCP Server]
    Client[MCP Client] -->|requests| FastMCP
    FastMCP -->|on_message / tools/call| Middleware
    Middleware -->|transformed request| FastMCP
    FastMCP -->|component lookup| LocalProvider
    LocalProvider -->|handler| Decorators

Tools

Tools are the primary mechanism for exposing callable actions to MCP clients. They are most commonly authored with the @tool decorator, which wraps a plain Python function and produces a FunctionTool instance registered with the local provider.

Source: fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py

The decorator signature supports common knobs surfaced in the community:

Per-tool timeouts are currently declared individually; a server-wide default via FastMCP(default_tool_timeout=...) is a tracked enhancement (community issue #4304). When a tool times out, the server raises McpError with code -32000; community issue #4305 requests a hook to customize that error message and exception type.

The base Tool class defines common behavior such as schema generation, enable/disable state, and outputSchema synthesis. Source: fastmcp_slim/fastmcp/tools/base.py.

FunctionTool extends that base and is the implementation behind @tool. It accepts the wrapped function plus the decorator options and converts function signatures into JSON Schema for the client. Source: fastmcp_slim/fastmcp/tools/function_tool.py.

A known limitation (community issue #4306): json_schema_to_type raises RecursionError when an outputSchema contains a self-referential $ref. Self-referential schemas should be avoided until recursive type generation is supported.

Resources

Resources expose read-only data by URI. They are registered with @resource for static URIs and with a template decorator for parameterized URIs.

Source: fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py

Community-reported behavior to be aware of:

• URI template matching uses match_uri_template, which strictly expects {var} to match [^/]+. Combined with raw string replacement in expand_uri_template, this causes reserved characters in path values to fail round-tripping (community issue #4326).
• Resources can be enabled, disabled, and carry meta just like tools.

The component-manager contrib module demonstrates a production use of resource enable/disable, exposing HTTP endpoints such as POST /resources/example://test/{id}/enable. Source: fastmcp_slim/fastmcp/contrib/component_manager/README.md.

Prompts

Prompts provide reusable message templates. They are registered with @prompt and follow the same enable/disable and meta options as tools and resources.

Source: fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py

Middleware

Middleware wraps inbound MCP messages to add cross-cutting behavior — caching, rate limiting, logging, and authentication-adjacent tasks.

Two known sharp edges appear in recent releases:

1. Caching middleware crash on cache miss. On fastmcp>=3.4.0, requests that miss the cache crash with TypeError: FastMCP._run_middleware.<locals>.wrapped() got an unexpected keyword argument 'context' (community issue #4300). The wrapped middleware signature must accept a context argument.
2. on_message does not see unauthenticated requests. Middleware is invoked after auth succeeds, so requests rejected by authentication cannot be observed by middleware for logging or rate limiting (community issue #4309).

Rate-limiting middleware (RateLimitingMiddleware, SlidingWindowRateLimitingMiddleware) uses a synchronous Callable[[MiddlewareContext], str] for get_client_id. Passing an async callable is silently ignored and effectively disables per-client limiting (community issue #4320). When the token does not embed a tenant/user id, supply a sync resolver that derives the id from the context.

Local Provider and Registration

LocalProvider is the component registry backing a FastMCP instance. It owns the maps from component name/URI to handler and is consulted on every component lookup, including for mounted sub-servers.

Source: fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py

An alternative registration style is MCPMixin, a contrib class that lets developers decorate methods on their own classes (@mcp_tool, @mcp_resource, @mcp_prompt) and then call register_all() to attach them to a server. This is convenient when organizing components as methods rather than free functions.

Source: fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md

Operational Notes

• Auth observability. Authentication is enforced before middleware runs; observability stacks must rely on transport-level logs for unauthenticated traffic (community issue #4309).
• Destructive capabilities. FastMCP does not currently warn or gate tools whose handlers shell out, delete files, or read environment variables. The destructiveHint annotation can hint intent to clients, but there is no server-side policy enforcement (community issue #4318).
• Proxy lifecycle. StatefulProxyClient.clear() can race with per-session cleanup callbacks registered by FastMCPProxy.new_stateful(), producing a KeyError on shutdown (community issue #4321).
• Latest release. v3.4.2 restores JWT compatibility for providers that emit private, non-critical JWS header parameters (e.g. Clerk's cat), without relaxing the rejection of unsupported critical headers.

See Also

• Server Auth and Providers
• Client and Proxy
• OpenAPI Provider
• Contrib Modules

Related Pages

Related topics: Overview and Core Architecture, Clients, Apps, Tasks, and Extensibility

Authentication, Providers, and Proxy

FastMCP exposes a pluggable authentication subsystem that lets a server require and verify bearer tokens before any MCP request is handled. The system is built on three layers: a token verifier contract (TokenVerifier / AccessToken), reusable provider integrations (Auth0, GitHub, Google, Discord, JWT, debug), and two proxy classes (OAuthProxy, OIDCProxy) that mediate the upstream OAuth/OIDC handshake on behalf of MCP clients. All three layers are wired into FastMCP through the auth= constructor argument, and an out-of-the-band OAuthCallback server handles the redirect landing page on the client side.

Core Authentication: AccessToken and TokenVerifier

At the center of the system is an abstract TokenVerifier class. Subclasses implement verify_token(token: str) -> AccessToken to return a structured AccessToken carrying the subject, scopes, raw claims, and optional expiration. The base class enforces a positive required_scopes policy at construction time and exposes helper methods such as AccessToken.has_scope() and verify_token() so callers can introspect claims without re-parsing the raw JWT body.

The contract is deliberately small. AuthProvider (in auth.py) is an alias protocol that wraps a verifier, letting FastMCP accept either a concrete provider instance or any object that satisfies the protocol. This is what enables lightweight integrations like DebugTokenVerifier to drop in for testing without inheriting the OAuth machinery. Source: fastmcp_slim/fastmcp/server/auth/auth.py.

from fastmcp.server.auth.providers.debug import DebugTokenVerifier

auth = DebugTokenVerifier(
    validate=lambda token: token.startswith("valid-"),
)

DebugTokenVerifier accepts any non-empty token by default and is explicitly marked as appropriate only for "controlled environments" — its docstring warns it bypasses standard security checks. Source: fastmcp_slim/fastmcp/server/auth/providers/debug.py.

The OAuth/OIDC Proxy Layer

When the upstream identity provider is a remote OAuth or OIDC server, FastMCP does not require the MCP server itself to implement the full authorization-code dance. Instead, the OAuthProxy class (in oauth_proxy.py) registers the server as a client to the upstream IdP, manages the client-registration storage, proxies the authorize and token endpoints, and re-signs short-lived FastMCP access tokens. OIDCProxy is a specialization that additionally auto-discovers the upstream issuer from a .well-known/openid-configuration URL and validates ID tokens. Source: fastmcp_slim/fastmcp/server/auth/oauth_proxy.py, fastmcp_slim/fastmcp/server/auth/oidc_proxy.py.

Both proxies accept a consistent surface: client_id, client_secret, base_url, required_scopes, redirect_path, allowed_client_redirect_uris, client_storage, and jwt_signing_key. They also expose require_authorization_consent (a bool or the literal "remember" / "external") to control the consent screen, and a forward_resource flag for OAuth 2.1 resource indicators. Source: fastmcp_slim/fastmcp/server/auth/providers/auth0.py, fastmcp_slim/fastmcp/server/auth/providers/google.py.

flowchart LR
    Client[MCP Client] -->|authorize request| Proxy[OAuthProxy / OIDCProxy]
    Proxy -->|upstream authorize| IdP[(Upstream OAuth/OIDC IdP)]
    IdP -->|auth code| Proxy
    Proxy -->|exchange + sign JWT| Client
    Client -->|bearer token| MCP[FastMCP Server]
    MCP -->|TokenVerifier.verify_token| Proxy

For clients that cannot run a local callback listener, FastMCP ships a reusable OAuthCallback server built on Starlette + Uvicorn that renders an HTML status page (OAuthCallbackResult) and signals completion via an anyio.Event. Source: fastmcp_slim/fastmcp/client/oauth_callback.py.

Built-in Providers

Each provider in fastmcp_slim/fastmcp/server/auth/providers/ subclasses OAuthProxy, OIDCProxy, or TokenVerifier and supplies sane defaults plus a token-verification strategy tuned to the IdP's token format (opaque vs. JWT). The table below summarizes the provider layout observed in the repository.

The JWT verifier distinguishes algorithms by prefix — HS*, RS*/PS*, and ES* — and uses joserfc for decoding. As of v3.4.2, "FastMCP 3.4.2 restores JWT compatibility for providers that include private, non-critical JWS header parameters. Tokens from providers like Clerk can carry header metadata such as cat without being rejected before signature and claim validation, while unsupported critical headers are still rejected." Source: fastmcp_slim/fastmcp/server/auth/providers/jwt.py.

Opaque-token providers (GitHub, Discord) call the upstream introspection/user-info endpoint on every request by default; both expose a cache_ttl_seconds knob to amortize that round-trip. GitHub's verifier additionally accepts a required_scopes list and delegates scope parsing to fastmcp.utilities.auth.parse_scopes. Source: fastmcp_slim/fastmcp/server/auth/providers/github.py.

Community Topics, Limitations, and Pitfalls

Several open issues map directly onto the auth subsystem and are worth understanding before deploying:

• Keycloak DCR is not yet a first-class provider (#1918). Until it lands, Keycloak can be integrated by subclassing OIDCProxy with the realm's discovery URL.
• Multi-tenant OAuthProxy (#1802) is still single-upstream; routing by tenant context requires custom logic in client_storage.
• Loopback redirect_uri validation (#3588) — clients declaring redirect_uris without a port (e.g. http://localhost/callback) currently fail CIMD validation when the actual redirect uses a dynamic port, contradicting RFC 8252 §7.3.
• OAuth 2.1 full authorization (#825) — Claude Desktop Integrations drive demand for richer flows beyond bearer-only auth.
• Inspector vs. Client divergence (#972) — OAuth that works against MCP Inspector may not work against Claude Integrations or the FastMCP Client, often because the callback URL/port differs between clients. The mounted-provider example (examples/auth/mounted/) demonstrates how to expose multiple providers under path-aware discovery (/.well-known/oauth-authorization-server/api/mcp/{provider}).

A second set of cross-cutting issues touches auth-adjacent subsystems: on_message middleware is not invoked for unauthenticated requests (#4309), so failed-auth attempts cannot be observed by user middleware; and RateLimitingMiddleware.get_client_id is typed sync-only and silently disables rate limiting when given an async callable (#4320).

See Also

• OAuth Callback Server & Client Flows — client-side OAuthCallback lifecycle.
• Bearer Token Authentication — TokenVerifier usage patterns.
• Multi-Provider OAuth Example — path-aware discovery across mounted servers.
• Component Manager (contrib) — runtime enable/disable of tools, often paired with scope-gated auth.

Related Pages

Related topics: Overview and Core Architecture, Server Core: Tools, Resources, Prompts, and Middleware

Clients, Apps, Tasks, and Extensibility

FastMCP is a Python framework for building and consuming Model Context Protocol (MCP) servers. Beyond wrapping Python functions as tools, resources, and prompts, FastMCP ships a rich client surface, an "Apps" model for interactive UIs, a task abstraction aligned with SEP-1686, and a layered extensibility model (contrib modules, middleware, and pluggable auth providers). This page documents those four pillars and how they fit together.

Clients

The FastMCP client is a mixin-based, transport-agnostic connection layer. It exposes dedicated mixins for each MCP concept, including tools, resources, and prompts. For example, the ClientToolsMixin provides list_tools_mcp, list_tools, and call_tool_mcp, with built-in auto-pagination that walks nextCursor values until exhausted or until AUTO_PAGINATION_MAX_PAGES (250) is hit, deduplicating cursors to guard against server-side loops. Source: fastmcp_slim/fastmcp/client/mixins/tools.py.

The ClientResourcesMixin mirrors this design for resources with list_resources_mcp, pagination helpers, and a ResourceTaskResponseUnion that accepts either a CreateTaskResult or a ReadResourceResult, enabling graceful degradation when servers do not advertise task support. Source: fastmcp_slim/fastmcp/client/mixins/resources.py.

Authentication for clients is orchestrated around an OAuth callback server. The module ships a renderable status page, plus CallbackResponse and OAuthCallbackResult dataclasses that carry the code, state, and any error/error_description back to the calling coroutine via an anyio.Event. Source: fastmcp_slim/fastmcp/client/oauth_callback.py.

Apps

FastMCP "Apps" extend plain tools with interactive UIs rendered inside the conversation. The pattern links a tool to a ui:// resource via an AppConfig, and serves the resource as embedded HTML that loads the @modelcontextprotocol/ext-apps JavaScript SDK. The QR code example demonstrates the full chain: a generate_qr tool returns base64 PNG bytes, and a ui://qr-server/view.html resource hosts the iframe UI with a ResourceCSP(resource_domains=["https://unpkg.com"]) declaration so the host can emit a valid Content-Security-Policy header. Source: examples/apps/qr_server/README.md.

A second extensibility pattern, the "Skills" provider, exposes agent skill folders (such as Claude Code skills) as MCP resources. A SkillProvider wraps a single skill directory, while a SkillsDirectoryProvider scans a parent directory and instantiates one SkillProvider per child folder, with progressive disclosure exposing a synthetic skill://{name}/_manifest alongside the main SKILL.md resource. Source: examples/skills/README.md.

Tasks

FastMCP adopts the SEP-1686 task abstraction to let long-running tool or resource invocations return a CreateTaskResult handle synchronously, which the client later polls for completion. To remain compatible with servers that have not yet shipped task support, the client mixins type the response union as RootModel[mcp.types.CreateTaskResult | mcp.types.CallToolResult] for tools and the equivalent ResourceTaskResponseUnion for resources, so a non-task server returning a direct result is transparently accepted. Source: fastmcp_slim/fastmcp/client/mixins/tools.py, fastmcp_slim/fastmcp/client/mixins/resources.py.

This design also surfaces a known ergonomic gap: when @tool(timeout=...) fires, FastMCP hardcodes the warning text and raises McpError with code -32000, with no hook to customize either the message or the exception type — a long-standing community ask tracked in issue #4305. Source: stored community evidence for PrefectHQ/fastmcp#4305.

Extensibility

FastMCP exposes three extensibility surfaces. The first is the fastmcp.contrib namespace, which holds community-maintained modules that extend core functionality without stability guarantees. Source: fastmcp_slim/fastmcp/contrib/README.md. A representative module is the Component Manager, which adds HTTP endpoints for enabling and disabling tools, resources, and prompts at runtime, supports mounted sub-servers, and allows custom API root paths and OAuth scope guards. Source: fastmcp_slim/fastmcp/contrib/component_manager/README.md.

The second surface is pluggable authentication. DebugTokenVerifier is the escape hatch for testing and opaque tokens, accepting any non-empty token by default and optionally delegating to a sync or async validate callable. Source: fastmcp_slim/fastmcp/server/auth/providers/debug.py. JWTVerifier performs full JWS validation using joserfc, with SUPPORTED_JWS_HEADER_FIELDS defined as frozenset(JWS_HEADER_REGISTRY) so v3.4.2+ tolerates private, non-critical header parameters (e.g., Clerk's cat) while still rejecting unsupported critical headers. Source: fastmcp_slim/fastmcp/server/auth/providers/jwt.py. GitHubProvider wraps the OAuth proxy and uses GitHub's user API to verify opaque tokens. Source: fastmcp_slim/fastmcp/server/auth/providers/github.py.

The third surface is middleware, which sits between transport and component dispatch and is the focus of several active community discussions. Known limitations include: caching middleware crashing with TypeError: ... got an unexpected keyword argument 'context' on cache miss in v3.4.0+ (#4300); RateLimitingMiddleware.get_client_id rejecting async callables at the type level and silently disabling rate limiting (#4320); and on_message middleware not running for unauthenticated requests, so rejected requests are invisible to observers (#4309). Source: stored community evidence for #4300, #4320, and #4309.

flowchart LR
    A[Python functions] --> B[FastMCP Server]
    B --> C[Tools / Resources / Prompts]
    B --> D[MCP Apps ui:// resources]
    C --> E[SEP-1686 Tasks]
    C --> F[Middleware pipeline]
    F --> G[Auth providers<br/>JWT / GitHub / Debug]
    H[FastMCP Client] -->|transports| B
    H --> I[contrib modules<br/>e.g. Component Manager]

See Also

• Servers and Components
• Authentication and OAuth
• Middleware and Tool Timeouts
• MCP Apps and Resource Linking

Doramagic Pitfall Log

Found 33 structured pitfall item(s), including 12 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4306

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4241

3. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4300

4. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4321

5. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4305

6. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4326

7. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
• User impact: Developers may expose sensitive permissions or credentials: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: No guardrails against destructive tool capabilities (shell exec, file deletion, env access). Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4318

8. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: on_message middleware not called for unauthenticated requests
• User impact: Developers may expose sensitive permissions or credentials: on_message middleware not called for unauthenticated requests
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: on_message middleware not called for unauthenticated requests. Context: Observed when using python, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4309

9. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4318

10. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4320

11. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4304

12. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4309

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using fastmcp with real data or production workflows.

• feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout def - github / github_issue
• CIMD redirect_uri validation rejects loopback URIs with dynamic ports (R - github / github_issue
• Upgrade checks failing on main branch - github / github_issue
• caching middleware broken - github / github_issue
• RateLimitingMiddleware.get_client_id passing an async callable silently - github / github_issue
• FastMCP StatefulProxyClient.clear() can cause KeyError during proxy sess - github / github_issue
• No guardrails against destructive tool capabilities (shell exec, file de - github / github_issue
• expand_uri_template and match_uri_template do not round-trip path values - github / github_issue
• on_message middleware not called for unauthenticated requests - github / github_issue
• RecursionError in json_schema_to_type on self-referential $ref in tool o - github / github_issue
• feat: hook or factory for customizing tool timeout error messages and ty - github / github_issue
• v3.4.2: Heads Up - github / github_release