# https://github.com/PrefectHQ/fastmcp Project Manual

Generated at: 2026-06-21 10:02:06 UTC

## Table of Contents

- [Overview and Core Architecture](#page-overview)
- [Server Core: Tools, Resources, Prompts, and Middleware](#page-server-core)
- [Authentication, Providers, and Proxy](#page-auth-providers)
- [Clients, Apps, Tasks, and Extensibility](#page-clients-apps-tasks)

<a id='page-overview'></a>

## Overview and Core Architecture

### Related Pages

Related topics: [Server Core: Tools, Resources, Prompts, and Middleware](#page-server-core), [Authentication, Providers, and Proxy](#page-auth-providers)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)
- [fastmcp_slim/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/README.md)
- [fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
- [fastmcp_slim/fastmcp/client/mixins/tools.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py)
- [fastmcp_slim/fastmcp/client/mixins/resources.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/resources.py)
- [fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)
- [fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- [fastmcp_slim/fastmcp/cli/install/cursor.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/install/cursor.py)
- [fastmcp_slim/fastmcp/cli/install/gemini_cli.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/install/gemini_cli.py)
- [fastmcp_slim/fastmcp/cli/run.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/run.py)
- [fastmcp_slim/fastmcp/contrib/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/README.md)
- [fastmcp_slim/fastmcp/contrib/component_manager/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md)
- [fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md)
- [examples/apps/qr_server/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md)
- [examples/fastmcp_config_demo/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/fastmcp_config_demo/README.md)
</details>

# 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)](https://modelcontextprotocol.io/). 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](https://github.com/PrefectHQ/fastmcp/blob/main/README.md).

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

| Surface | Role |
| --- | --- |
| **Servers** | Wrap Python functions into MCP-compliant tools, resources, and prompts |
| **Clients** | Connect to any MCP server (local or remote, programmatic or CLI) |
| **Apps** | Attach interactive UIs to tools so they render inside the conversation |

Source: [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/README.md).

## Core Architecture Components

```mermaid
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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py), [fastmcp_slim/fastmcp/client/mixins/resources.py](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/install/cursor.py), [fastmcp_slim/fastmcp/cli/install/gemini_cli.py](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/issues/4304) asks for `FastMCP(default_tool_timeout=...)`. Issue [#4305](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/4300)), `RateLimitingMiddleware.get_client_id` silently fails when an async callable is passed because its type is sync-only ([#4320](https://github.com/PrefectHQ/fastmcp/issues/4320)), and `on_message` middleware does not fire for requests rejected by auth ([#4309](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/3588)). Full OAuth 2.1 support ([#825](https://github.com/PrefectHQ/fastmcp/issues/825)), Keycloak with Dynamic Client Registration ([#1918](https://github.com/PrefectHQ/fastmcp/issues/1918)), and multi-tenant routing in `OAuthProxy` ([#1802](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/4326)).
- **Schema recursion** — `json_schema_to_type` raises `RecursionError` on self-referential `$ref` entries in a tool `outputSchema`, breaking client-side type construction ([#4306](https://github.com/PrefectHQ/fastmcp/issues/4306)).
- **Developer ergonomics** — Hot-reload (`--reload`) has been requested since [#616](https://github.com/PrefectHQ/fastmcp/issues/616), and [#4318](https://github.com/PrefectHQ/fastmcp/issues/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](https://gofastmcp.com/servers/server)
- [Clients documentation](https://gofastmcp.com/clients/client)
- [Apps overview](https://gofastmcp.com/apps/overview)
- [Installation guide](https://gofastmcp.com/getting-started/installation)
- [Quickstart](https://gofastmcp.com/getting-started/quickstart)
- [Component Manager (contrib)](https://gofastmcp.com/servers/component-manager)
- [MCP Mixin (contrib)](https://github.com/PrefectHQ/fastmcp/tree/main/fastmcp_slim/fastmcp/contrib/mcp_mixin)

---

<a id='page-server-core'></a>

## Server Core: Tools, Resources, Prompts, and Middleware

### Related Pages

Related topics: [Overview and Core Architecture](#page-overview), [Authentication, Providers, and Proxy](#page-auth-providers), [Clients, Apps, Tasks, and Extensibility](#page-clients-apps-tasks)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py)
- [fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py)
- [fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py)
- [fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py)
- [fastmcp_slim/fastmcp/tools/function_tool.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/tools/function_tool.py)
- [fastmcp_slim/fastmcp/tools/base.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/tools/base.py)
- [fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md)
- [fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)
</details>

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

```mermaid
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:

| Option | Purpose |
| --- | --- |
| `name` | Override the tool name advertised to the client |
| `description` | Override the auto-generated description |
| `enabled` | Toggle the tool on/off at registration time |
| `exclude_args` | Hide selected parameters from the schema |
| `annotations` | Set `ToolAnnotations` hints (e.g. `destructiveHint`) |
| `meta` | Attach arbitrary metadata |
| `timeout` | Per-tool execution timeout |

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](auth-providers.md)
- [Client and Proxy](client-proxy.md)
- [OpenAPI Provider](openapi-provider.md)
- [Contrib Modules](contrib.md)

---

<a id='page-auth-providers'></a>

## Authentication, Providers, and Proxy

### Related Pages

Related topics: [Overview and Core Architecture](#page-overview), [Clients, Apps, Tasks, and Extensibility](#page-clients-apps-tasks)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [fastmcp_slim/fastmcp/server/auth/auth.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/auth.py)
- [fastmcp_slim/fastmcp/server/auth/oauth_proxy.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/oauth_proxy.py)
- [fastmcp_slim/fastmcp/server/auth/oidc_proxy.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/oidc_proxy.py)
- [fastmcp_slim/fastmcp/server/auth/providers/auth0.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/auth0.py)
- [fastmcp_slim/fastmcp/server/auth/providers/github.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/github.py)
- [fastmcp_slim/fastmcp/server/auth/providers/google.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/google.py)
- [fastmcp_slim/fastmcp/server/auth/providers/discord.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/discord.py)
- [fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)
- [fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- [fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
</details>

# 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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/auth.py).

```python
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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/oauth_proxy.py), [fastmcp_slim/fastmcp/server/auth/oidc_proxy.py](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/auth0.py), [fastmcp_slim/fastmcp/server/auth/providers/google.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/google.py).

```mermaid
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](https://github.com/PrefectHQ/fastmcp/blob/main/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.

| Provider | Module | Base Class | Token Format | Key Configuration |
|---|---|---|---|---|
| Auth0 | `providers/auth0.py` | `OIDCProxy` | JWT (RS256 via JWKS) | `config_url`, `audience`, `base_url` |
| GitHub | `providers/github.py` | `OAuthProxy` + `GitHubTokenVerifier` | Opaque, validated via GitHub API | `client_id`, `client_secret`, optional `cache_ttl_seconds` |
| Google | `providers/google.py` | `OAuthProxy` | Opaque + ID token | `client_id`, `client_secret`, `base_url` |
| Discord | `providers/discord.py` | `OAuthProxy` + `DiscordTokenVerifier` | Opaque, validated via Discord tokeninfo API | `expected_client_id`, `timeout_seconds` |
| JWT (generic) | `providers/jwt.py` | `TokenVerifier` | JWT (HS/RS/PS/ES) | `public_key` or JWKS URL, `audience`, `issuer` |
| Debug | `providers/debug.py` | `TokenVerifier` | Anything | `validate: Callable[[str], bool]` |

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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/blob/main/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](https://github.com/PrefectHQ/fastmcp/issues/1918)). Until it lands, Keycloak can be integrated by subclassing `OIDCProxy` with the realm's discovery URL.
- **Multi-tenant `OAuthProxy`** ([#1802](https://github.com/PrefectHQ/fastmcp/issues/1802)) is still single-upstream; routing by tenant context requires custom logic in `client_storage`.
- **Loopback `redirect_uri` validation** ([#3588](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/825)) — Claude Desktop Integrations drive demand for richer flows beyond bearer-only auth.
- **Inspector vs. Client divergence** ([#972](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/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](https://github.com/PrefectHQ/fastmcp/issues/4320)).

## See Also

- [OAuth Callback Server & Client Flows](https://gofastmcp.com/servers/auth/oauth) — client-side `OAuthCallback` lifecycle.
- [Bearer Token Authentication](https://gofastmcp.com/servers/auth/bearer) — `TokenVerifier` usage patterns.
- [Multi-Provider OAuth Example](https://github.com/PrefectHQ/fastmcp/blob/main/examples/auth/mounted/README.md) — path-aware discovery across mounted servers.
- [Component Manager (contrib)](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md) — runtime enable/disable of tools, often paired with scope-gated auth.

---

<a id='page-clients-apps-tasks'></a>

## Clients, Apps, Tasks, and Extensibility

### Related Pages

Related topics: [Overview and Core Architecture](#page-overview), [Server Core: Tools, Resources, Prompts, and Middleware](#page-server-core)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)
- [fastmcp_slim/README.md](https://github.com/PrefectHQ/fastmcp_slim/blob/main/README.md)
- [fastmcp_slim/fastmcp/client/mixins/tools.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py)
- [fastmcp_slim/fastmcp/client/mixins/resources.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/resources.py)
- [fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
- [fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- [fastmcp_slim/fastmcp/server/auth/providers/github.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/github.py)
- [fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)
- [fastmcp_slim/fastmcp/contrib/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/README.md)
- [fastmcp_slim/fastmcp/contrib/component_manager/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md)
- [examples/apps/qr_server/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md)
- [examples/skills/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/skills/README.md)
- [examples/fastmcp_config_demo/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/fastmcp_config_demo/README.md)
</details>

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

```mermaid
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](servers-and-components.md)
- [Authentication and OAuth](authentication-and-oauth.md)
- [Middleware and Tool Timeouts](middleware-and-tool-timeouts.md)
- [MCP Apps and Resource Linking](mcp-apps-and-resource-linking.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: PrefectHQ/fastmcp

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4306

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4241

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4300

## 4. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4321

## 5. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4305

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4326

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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)
- 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
- Evidence strength: source_linked
- 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
- 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4318

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4320

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4304

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4309

## 13. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Upgrade checks failing on main branch
- User impact: Developers may fail before the first successful local run: Upgrade checks failing on main branch
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4241

## 14. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: caching middleware broken
- User impact: Developers may fail before the first successful local run: caching middleware broken
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4300

## 15. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.3.1: Loop There It Is
- User impact: Upgrade or migration may change expected behavior: v3.3.1: Loop There It Is
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.1

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.4.0: Remote Control
- User impact: Upgrade or migration may change expected behavior: v3.4.0: Remote Control
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.4.1: Floor It
- User impact: Upgrade or migration may change expected behavior: v3.4.1: Floor It
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.1

## 18. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- User impact: Developers may misconfigure credentials, environment, or host setup: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/3588

## 19. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- User impact: Developers may misconfigure credentials, environment, or host setup: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4304

## 20. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat: hook or factory for customizing tool timeout error messages and types
- User impact: Developers may misconfigure credentials, environment, or host setup: feat: hook or factory for customizing tool timeout error messages and types
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4305

## 21. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v3.4.0b1: Remote Possibility
- User impact: Upgrade or migration may change expected behavior: v3.4.0b1: Remote Possibility
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0b1

## 22. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v3.4.2: Heads Up
- User impact: Upgrade or migration may change expected behavior: v3.4.2: Heads Up
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2

## 23. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/PrefectHQ/fastmcp

## 24. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- User impact: Developers may hit a documented source-backed failure mode: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4321

## 25. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- User impact: Developers may hit a documented source-backed failure mode: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4320

## 26. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- User impact: Developers may hit a documented source-backed failure mode: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4306

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- User impact: Developers may hit a documented source-backed failure mode: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4326

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp

## 29. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/PrefectHQ/fastmcp

## 30. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/PrefectHQ/fastmcp

## 31. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/3588

## 32. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp

## 33. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp

<!-- canonical_name: PrefectHQ/fastmcp; human_manual_source: deepwiki_human_wiki -->