๐ The fast, Pythonic way to build MCP servers and clients.
docs: correct getting started, CLI and deployment pages against main (#6410)
nate nowackc8303b40b424
diff --git a/docs/cli/auth.mdx b/docs/cli/auth.mdxindex 5a0a4314c..2345df2de 100644--- a/docs/cli/auth.mdx+++ b/docs/cli/auth.mdx@@ -72,7 +72,7 @@ The validator checks that the URL is valid (HTTPS, non-root path), the documentOn success:-```+```textโ Fetching https://myapp.example.com/oauth/client.json...โ Valid CIMD documentdiff --git a/docs/cli/client.mdx b/docs/cli/client.mdxindex e2f8ed6f0..ccceb21ee 100644--- a/docs/cli/client.mdx+++ b/docs/cli/client.mdx@@ -135,14 +135,14 @@ fastmcp call server.py summarize --prompt --input-json '{"topic": "weather"}'## Discovering Configured Servers-`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks:--- **Claude Desktop** โ `claude_desktop_config.json`-- **Claude Code** โ `~/.claude.json`-- **Cursor** โ `.cursor/mcp.json` (walks up from current directory)-- **Gemini CLI** โ `~/.gemini/settings.json`-- **Goose** โ `~/.config/goose/config.yaml`-- **Project** โ `./mcp.json` in the current directory+`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks these sources, listed with the source name you use in `--source` and `source:name`:++- **Claude Desktop** (`claude-desktop`) โ `claude_desktop_config.json`+- **Claude Code** (`claude-code`) โ `~/.claude.json`+- **Cursor** (`cursor`) โ `.cursor/mcp.json` (walks up from current directory)+- **Gemini CLI** (`gemini`) โ `~/.gemini/settings.json` and `.gemini/settings.json` in the current directory+- **Goose** (`goose`) โ `~/.config/goose/config.yaml`+- **Project** (`project`) โ `./mcp.json` in the current directoryGoose discovery includes enabled `stdio` and `streamable_http` extensions, as well as legacy `sse` entries. Streamable HTTP extensions retain their configured `headers` when resolved by name.diff --git a/docs/cli/generate-cli.mdx b/docs/cli/generate-cli.mdxindex 812e5b68d..c393511ed 100644--- a/docs/cli/generate-cli.mdx+++ b/docs/cli/generate-cli.mdx@@ -9,7 +9,7 @@ import { VersionBadge } from '/snippets/version-badge.mdx'<VersionBadge version="3.0.0" />-`fastmcp list` and `fastmcp call` are general-purpose โ you always specify the server, the tool name, and the arguments from scratch. `fastmcp generate-cli` goes further: it connects to a server, reads its tool schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels hand-written for that specific server.+`fastmcp list` and `fastmcp call` are general-purpose โ you always specify the server, the tool name, and the arguments from scratch. `fastmcp generate-cli` goes further: it connects to a server, reads its tool schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags and help text. The result is a CLI that feels hand-written for that specific server.MCP tool schemas already contain everything a CLI framework needs โ parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that into [cyclopts](https://cyclopts.readthedocs.io/) commands, so JSON Schema types become Python type annotations, descriptions become `--help` text, and required parameters become mandatory flags.@@ -33,28 +33,30 @@ fastmcp generate-cli weather -fThe generated script is a regular Python file โ executable, editable, and yours:-```+```text$ python cli.py call-tool --help-Usage: weather-cli call-tool COMMAND+Usage: weather call-tool COMMANDCall a tool on the server-Commands:- get_forecast Get the weather forecast for a city.- search_city Search for a city by name.+โญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ+โ get_forecast Get the weather forecast for a city. โ+โ search_city Search for a city by name. โ+โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ```Each tool has typed parameters with help text pulled directly from the server's schema:-```+```text$ python cli.py call-tool get_forecast --help-Usage: weather-cli call-tool get_forecast [OPTIONS]+Usage: weather call-tool get_forecast --city STR [OPTIONS]Get the weather forecast for a city.-Options:- --city [str] City name (required)- --days [int] Number of forecast days (default: 3)+โญโ Parameters โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ+โ * --city City name [required] โ+โ --days Number of forecast days [default: 3] โ+โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ```Beyond tool commands, the script includes generic MCP operations โ `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt` โ that always reflect the server's current state, even if tools have changed since generation.diff --git a/docs/cli/inspecting.mdx b/docs/cli/inspecting.mdxindex 4039e45f8..7e8a29704 100644--- a/docs/cli/inspecting.mdx+++ b/docs/cli/inspecting.mdx@@ -15,20 +15,22 @@ import { VersionBadge } from '/snippets/version-badge.mdx'fastmcp inspect server.py```-```-Server: MyServer-Instructions: A helpful MCP server-Version: 1.0.0--Components:- Tools: 5- Prompts: 2- Resources: 3- Templates: 1--Environment:- FastMCP: 2.0.0- MCP: 1.0.0+```text+Server+ Name: MyServer+ Version: 1.0.0+ Generation: 2+ Instructions: A helpful MCP server++Components+ Tools: 5+ Prompts: 2+ Resources: 3+ Templates: 1++Environment+ FastMCP: 4.2.0+ MCP: 2.3.0Use --format [fastmcp|mcp] for complete JSON output```@@ -37,7 +39,7 @@ Use --format [fastmcp|mcp] for complete JSON outputFor programmatic use, two JSON formats are available:-**FastMCP format** (`--format fastmcp`) includes everything FastMCP knows about the server โ tool tags, enabled status, output schemas, annotations, and custom metadata. Field names use `snake_case`. This is the format for debugging and introspecting FastMCP servers.+**FastMCP format** (`--format fastmcp`) includes everything FastMCP knows about the server โ component keys, tags, output schemas, annotations, custom metadata, and the server's capabilities. Field names use `snake_case`. This is the format for debugging and introspecting FastMCP servers.**MCP protocol format** (`--format mcp`) shows exactly what MCP clients see through the protocol โ only standard MCP fields, `camelCase` names, no FastMCP-specific extensions. This is the format for verifying client compatibility and debugging what clients actually receive.diff --git a/docs/cli/install-mcp.mdx b/docs/cli/install-mcp.mdxindex 7d015592e..545e7c23a 100644--- a/docs/cli/install-mcp.mdx+++ b/docs/cli/install-mcp.mdx@@ -59,13 +59,13 @@ See [Server Configuration](/deployment/server-configuration) for the full config| Server Name | `--name`, `-n` | Custom name for the server || Editable Package | `--with-editable` | Install a directory in editable mode || Extra Packages | `--with` | Additional packages (repeatable) |-| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable) |-| Environment File | `--env-file` | Load env vars from a `.env` file |+| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable; not `stdio`) |+| Environment File | `--env-file` | Load env vars from a `.env` file (not `stdio`) || Python | `--python` | Python version (e.g., `3.11`) || Project | `--project` | Run within a uv project directory || Requirements | `--with-requirements` | Install from a requirements file || Config Path | `--config-path` | Custom path to Claude Desktop config directory (`claude-desktop` only) |-| Workspace | `--workspace` | Install to the workspace directory instead of globally (`cursor` only) |+| Workspace | `--workspace` | Write `.cursor/mcp.json` in this workspace directory instead of opening a deeplink (`cursor` only) || Copy | `--copy` | Copy the generated output to the clipboard (`mcp-json` and `stdio` only) |`goose` installs through a deeplink that runs your server with `uvx`, so it accepts only `--name`, `--with`, and `--python`. Options that depend on a local uv project โ `--with-editable`, `--project`, and `--with-requirements` โ are unavailable there. Deeplinks also cannot carry environment variables: passing `--env` or `--env-file` exits with an error directing you to `fastmcp install mcp-json`, which generates a config you can add to Goose by hand with the variables included.diff --git a/docs/cli/overview.mdx b/docs/cli/overview.mdxindex ab8de05f6..fca609c85 100644--- a/docs/cli/overview.mdx+++ b/docs/cli/overview.mdx@@ -66,7 +66,7 @@ fastmcp list --command 'npx -y @modelcontextprotocol/server-github'### Name-Based Resolution-If your servers are already configured in an editor or tool, you can refer to them by name. FastMCP scans configs from Claude Desktop, Claude Code, Cursor, Gemini CLI, and Goose:+If your servers are already configured in an editor or tool, you can refer to them by name. FastMCP scans configs from Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose, and a project-level `mcp.json`:```bashfastmcp list weatherdiff --git a/docs/cli/running.mdx b/docs/cli/running.mdxindex d2d6f3355..af766e58c 100644--- a/docs/cli/running.mdx+++ b/docs/cli/running.mdx@@ -122,7 +122,9 @@ Auto-reload is on by default โ save a file and the MCP server restarts automat| ------ | ---- | ----------- || MCP Port | `--mcp-port` | Port for the MCP server (default: `8000`) || Dev Port | `--dev-port` | Port for the dev UI (default: `8080`) |+| Host | `--host` | Bind address for both servers (default: `127.0.0.1`) || Auto-Reload | `--reload` / `--no-reload` | Watch for file changes (default: on) |+| Log Panel | `--log-panel` / `--no-log-panel` | Show a panel that logs MCP traffic in the dev UI (default: on) |## Development with the Inspector@@ -139,7 +141,7 @@ When you pass a Python file, `fastmcp dev inspector` imports it without executin</Warning><Tip>-The Inspector always runs your server via `uv run` in a subprocess โ it never uses your local environment directly. Specify dependencies with `--with`, `--with-editable`, `--with-requirements`, or through a `fastmcp.json` file.+The Inspector starts your server with `fastmcp run` in a subprocess. When you specify dependencies with `--with`, `--with-editable`, `--with-requirements`, `--python`, `--project`, or a `fastmcp.json` environment, that subprocess runs through `uv run`; otherwise it uses your current environment.</Tip><Warning>@@ -158,6 +160,7 @@ The Inspector connects over **stdio only**. When it launches, you may need to se| Python | `--python` | Python version || Project | `--project` | Run within a uv project directory || Requirements | `--with-requirements` | Install from a requirements file |+| Module Mode | `--module`, `-m` | Run a Python module via `python -m` instead of a file path |## Pre-Building Environmentsdiff --git a/docs/deployment/fastmcp-gateway.mdx b/docs/deployment/fastmcp-gateway.mdxindex ed67a6048..6c6a9f6c8 100644--- a/docs/deployment/fastmcp-gateway.mdx+++ b/docs/deployment/fastmcp-gateway.mdx@@ -116,7 +116,7 @@ Click **Deploy Server** and FastMCP Gateway will clone your repository, build yoOnce deployed, your server is accessible at a URL like:-```+```texthttps://your-server-name.fastmcp.app/mcp```diff --git a/docs/deployment/http.mdx b/docs/deployment/http.mdxindex 184798342..f4d5f2b1a 100644--- a/docs/deployment/http.mdx+++ b/docs/deployment/http.mdx@@ -82,6 +82,10 @@ The ASGI approach shines in production environments where you need reliability aBy default, your MCP server is accessible at `/mcp` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.```python+from fastmcp import FastMCP++mcp = FastMCP("My Server")+# Option 1: With mcp.run()mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp")@@ -196,10 +200,16 @@ When you put a FastMCP [proxy](/servers/providers/proxy) in front of another serHealth check endpoints are essential for monitoring your deployed server and ensuring it's responding correctly. FastMCP allows you to add custom routes alongside your MCP endpoints, making it easy to implement health checks that work with both deployment approaches.```python+from starlette.requests import Requestfrom starlette.responses import JSONResponse+from fastmcp import FastMCP++mcp = FastMCP("My Server")++@mcp.custom_route("/health", methods=["GET"])-async def health_check(request):+async def health_check(request: Request) -> JSONResponse:return JSONResponse({"status": "healthy", "service": "mcp-server"})```@@ -271,6 +281,8 @@ middleware = [allow_headers=["mcp-protocol-version","mcp-session-id",+ "mcp-method",+ "mcp-name","Authorization","Content-Type",],@@ -284,7 +296,7 @@ app = mcp.http_app(middleware=middleware)**Key configuration details:**- **`allow_origins`**: Specify exact origins (e.g., `["http://localhost:3000"]`) rather than `["*"]` for production deployments-- **`allow_headers`**: Must include `mcp-protocol-version`, `mcp-session-id`, and `Authorization` (for authenticated servers)+- **`allow_headers`**: Must include `mcp-protocol-version`, `mcp-session-id`, and `Authorization` (for authenticated servers). Clients on the `2026-07-28` protocol also send the `mcp-method` and `mcp-name` [routing headers](#gateway-routing-headers), plus one `Mcp-Param-*` header for each tool parameter annotated with `x-mcp-header`; list those too- **`expose_headers`**: Must include `mcp-session-id` so JavaScript can read the session ID from responses and send it in subsequent requestsWithout `expose_headers=["mcp-session-id"]`, browsers will receive the session ID but JavaScript won't be able to access it, causing session management to fail.@@ -306,11 +318,18 @@ When running tools that take a long time to complete, you may encounter issues wTo enable SSE polling, configure an `EventStore` when creating your HTTP application:```python+import asyncio+from fastmcp import FastMCP, Contextfrom fastmcp.server.event_store import EventStoremcp = FastMCP("My Server")++async def do_expensive_work() -> None:+ await asyncio.sleep(1)++@mcp.toolasync def long_running_task(ctx: Context) -> str:"""A task that takes several minutes to complete."""@@ -352,9 +371,12 @@ The `retry_interval` parameter (in milliseconds) controls how long clients waitBy default, `EventStore` uses in-memory storage. For production deployments with multiple server instances, you can provide a custom storage backend using the `key_value` package:```python+from fastmcp import FastMCPfrom fastmcp.server.event_store import EventStorefrom key_value.aio.stores.redis import RedisStore+mcp = FastMCP("My Server")+# Use Redis for distributed deploymentsredis_store = RedisStore(url="redis://localhost:6379")event_store = EventStore(@@ -738,6 +760,10 @@ app = mcp.http_app(stateless_http=True)**Option 2: Via `run()`**```python+from fastmcp import FastMCP++mcp = FastMCP("My Server")+if __name__ == "__main__":mcp.run(transport="http", stateless_http=True)```@@ -798,10 +824,14 @@ Production requires explicit key management to ensure tokens survive restarts anAdd two parameters to your auth provider:-```python {8-12}+```python {12-16}+import os++from cryptography.fernet import Fernetfrom key_value.aio.stores.redis import RedisStorefrom key_value.aio.wrappers.encryption import FernetEncryptionWrapper-from cryptography.fernet import Fernet++from fastmcp.server.auth.providers.github import GitHubProviderauth = GitHubProvider(client_id=os.environ["GITHUB_CLIENT_ID"],@@ -815,7 +845,7 @@ auth = GitHubProvider()```-Both parameters are required for production. Without an explicit signing key, keys are signed using a key derived from the client_secret, which will cause invalidation upon rotation of the client secret. Without persistent storage, tokens are local to the server and won't be trusted across hosts. **Wrap your storage backend in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without encryption, tokens are stored in plaintext.+Both parameters are required for production. Without an explicit signing key, tokens are signed with a key derived from the client secret, so rotating the client secret invalidates every issued token. Without persistent storage, tokens are local to the server and won't be trusted across hosts. **Wrap your storage backend in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without encryption, tokens are stored in plaintext.For more details on the token architecture and key management, see [OAuth Proxy Key and Storage Management](/servers/auth/oauth-proxy#key-and-storage-management).@@ -949,7 +979,7 @@ Note the trailing `/` on both `location /api/` and `proxy_pass http://127.0.0.1:## Testing Your Deployment-Once your server is deployed, you'll need to verify it's accessible and functioning correctly. For comprehensive testing strategies including connectivity tests, client testing, and authentication testing, see the [Testing Your Server](/development/tests) guide.+Once your server is deployed, connect to its URL with the [FastMCP client](/clients/client) to confirm it is reachable and lists the tools you expect. To test your server's behavior in code, see [Testing](/servers/testing).## Hosting Your Serverdiff --git a/docs/deployment/running-server.mdx b/docs/deployment/running-server.mdxindex d8615b717..c2af88ecf 100644--- a/docs/deployment/running-server.mdx+++ b/docs/deployment/running-server.mdx@@ -98,8 +98,11 @@ For production HTTP deployment with authentication and advanced configuration, sServer-Sent Events (SSE) transport was the original HTTP-based transport for MCP. While still supported for backward compatibility, it has limitations compared to the newer Streamable HTTP transport. SSE only supports server-to-client streaming, making it less efficient for bidirectional communication.```python+from fastmcp import FastMCP++mcp = FastMCP("MyServer")+if __name__ == "__main__":- # SSE transport - use HTTP instead for new projectsmcp.run(transport="sse", host="127.0.0.1", port=8000)```@@ -169,7 +172,7 @@ During development, you can use the `--reload` flag to automatically restart youfastmcp run server.py --reload```-The server watches for changes to Python files in the current directory and restarts automatically when you save changes. This provides a fast feedback loop during development without manually stopping and starting the server.+The server watches the current directory and restarts when you save a source file. The watcher covers Python files along with common frontend, markup, style, config, and image files (`.js`, `.ts`, `.html`, `.css`, `.json`, `.toml`, `.svg`, and similar), so changes to app assets also trigger a restart.```bash# Watch specific directories for changesdiff --git a/docs/deployment/server-configuration.mdx b/docs/deployment/server-configuration.mdxindex dd3905bd2..28ddc9213 100644--- a/docs/deployment/server-configuration.mdx+++ b/docs/deployment/server-configuration.mdx@@ -304,9 +304,9 @@ The `env` field in deployment configuration supports runtime interpolation of enWhen the server starts, FastMCP replaces `${ENVIRONMENT}`, `${DB_USER}`, etc. with values from your system's environment variables. If a variable doesn't exist, the placeholder is preserved as-is.-**Example**: If your system has `ENVIRONMENT=production` and `DB_HOST=db.example.com`:+For example, suppose your system has `ENVIRONMENT=production` and `DB_HOST=db.example.com`, and your configuration contains:+```json-// Configuration{"deployment": {"env": {@@ -315,8 +315,11 @@ When the server starts, FastMCP replaces `${ENVIRONMENT}`, `${DB_USER}`, etc. wi}}}+```-// Result at runtime+The server process then starts with these values:++```json{"API_URL": "https://api.production.example.com","DB_HOST": "db.example.com"@@ -472,7 +475,7 @@ A configuration optimized for local development:"environment": {"type": "uv","python": "3.12",- "dependencies": ["fastmcp[dev]"],+ "dependencies": ["fastmcp"],"editable": ["."]},"deployment": {diff --git a/docs/development/contributing.mdx b/docs/development/contributing.mdxindex c63473ca9..04bb6355c 100644--- a/docs/development/contributing.mdx+++ b/docs/development/contributing.mdx@@ -114,7 +114,7 @@ Read review-bot comments and maintainer replies, evaluate concrete findings, andThe [public backlog dashboard](https://prefecthq.github.io/fastmcp/) charts open issues and PRs, incoming work, and closure outcomes. Backlog snapshots update every 30 minutes; older reconstructed counts and the limits of closure history are identified on the page. The [maintenance status page](https://prefecthq.github.io/fastmcp/operations.html) reports automation health and the contributor queue twice a day. Check its timestamp before treating a status as current. The accompanying `status.json` uses the `fastmcp-maintenance/1` schema; `idle` means there was nothing to do, while `degraded` means a run failed.-Automation labels and deduplicates issues, enforces the contribution gate, explains CI failures, and checks new dependency releases nightly. Duplicate issues and reports still missing a reproduction after seven days without an author reply close automatically. Maintainers can request work with `/marvin`. A separate triage agent reproduces reported bugs and may leave comment-only reviews on linked pull requests; it does not assign contributors, approve, or merge.+Automation labels and deduplicates issues, enforces the contribution gate, explains CI failures, and checks new dependency releases nightly. Issues marked as duplicates close automatically after three days without further activity, and reports still missing a reproduction close after seven days without an author reply. Maintainers can request work with `/marvin`. A separate triage agent reproduces reported bugs and may leave comment-only reviews on linked pull requests; it does not assign contributors, approve, or merge.Maintainers decide assignments, merge readiness, changes to supported behavior or APIs, releases, and security-report classification. Release publishing and docs deployment run automatically after the corresponding maintainer actions; see [Releases](/development/releases#creating-releases).diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdxindex fbc0ef0b4..e5ce4d7d5 100644--- a/docs/getting-started/installation.mdx+++ b/docs/getting-started/installation.mdx@@ -50,16 +50,15 @@ FastMCP root path: ~/Developer/fastmcp### Dependency Licensing<Info>-FastMCP depends on Cyclopts for CLI functionality. Cyclopts v4 includes docutils as a transitive dependency, which has complex licensing that may trigger compliance reviews in some organizations.--If this is a concern, you can install Cyclopts v5 alpha which removes this dependency:+FastMCP depends on Cyclopts for its CLI. Older Cyclopts installs pull in docutils through rich-rst 1.x, and docutils has licensing that can trigger compliance reviews. rich-rst 2 no longer depends on docutils, and a fresh install resolves to rich-rst 2. If a scan flags docutils in an existing environment, upgrade both packages:```bash-pip install "cyclopts>=5.0.0a1"+pip install -U cyclopts rich-rst```-Alternatively, wait for the stable v5 release. See [this issue](https://github.com/BrianPugh/cyclopts/issues/672) for details.+See [this issue](https://github.com/BrianPugh/cyclopts/issues/672) for background.</Info>+## Upgrading### From FastMCP 3.0@@ -107,9 +106,10 @@ FastMCP 3.3 moved the importable code from the `fastmcp` distribution into `fast## Versioning Policy-FastMCP follows semantic versioning with pragmatic adaptations for the rapidly evolving MCP ecosystem. Breaking changes may occur in minor versions (e.g., 2.3.x to 2.4.0) when necessary to stay current with the MCP Protocol.+FastMCP follows semantic versioning with pragmatic adaptations for the rapidly evolving MCP ecosystem. Breaking changes may occur in minor versions (e.g., 4.1.x to 4.2.0) when necessary to stay current with the MCP Protocol.++For production use, use a lockfile or pin an exact version:-For production use, always pin to exact versions:```textfastmcp==4.0.5 # Good - an exact versionfastmcp>=4.0.0 # Bad - may install breaking changesdiff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdxindex 52a733060..f419cc305 100644--- a/docs/getting-started/quickstart.mdx+++ b/docs/getting-started/quickstart.mdx@@ -10,7 +10,7 @@ If you haven't already installed FastMCP, follow the [installation instructions]## Create a FastMCP Server-A FastMCP server is a collection of tools, resources, and other MCP components. To create a server, start by instantiating the `FastMCP` class.+A FastMCP server is a collection of tools, resources, and other MCP components. To create a server, start by instantiating the `FastMCP` class.Create a new file called `my_server.py` and add the following code:diff --git a/docs/getting-started/upgrading/from-fastmcp-3.mdx b/docs/getting-started/upgrading/from-fastmcp-3.mdxindex 598451237..d028e5d66 100644--- a/docs/getting-started/upgrading/from-fastmcp-3.mdx+++ b/docs/getting-started/upgrading/from-fastmcp-3.mdx@@ -113,7 +113,7 @@ The SDK v2 raises FastMCP's dependency floors, which matters before any of your### camelCase Field Access-Objects that FastMCP hands back to you โ the results of `client.list_tools()`, `client.call_tool_mcp()`, `client.read_resource()`, and the parameter objects passed to your sampling and elicitation handlers โ are SDK v2 objects with snake_case fields. FastMCP installs a compatibility bridge at import time that routes the old camelCase names to their new snake_case fields, so code written against FastMCP 2.x still reads correctly:+Objects that FastMCP hands back to you โ the results of `client.list_tools()`, `client.call_tool_mcp()`, `client.read_resource()`, and the parameter objects passed to your sampling and elicitation handlers โ are SDK v2 objects with snake_case fields. FastMCP installs a compatibility bridge at import time that routes the old camelCase names to their new snake_case fields, so code written against FastMCP 3.x still reads correctly:```pythonfrom pathlib import Path@@ -126,7 +126,7 @@ async def read_schema():return tools[0].inputSchema # still works, warns once```-Each bridged read emits a `FastMCPDeprecationWarning` pointing you at the snake_case name (`tools[0].input_schema` here). The bridge covers the fields users actually read: `inputSchema`/`outputSchema` on tools; `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` on tool annotations; `mimeType` on resources and content; `isError`/`structuredContent` on tool results; `nextCursor` on paginated results; `serverInfo`/`protocolVersion` on the initialize result; the sampling parameter fields (`systemPrompt`, `maxTokens`, `stopSequences`, `modelPreferences`, `toolChoice`); `requestedSchema` on elicitation parameters; `hasMore` and `resourceTemplates` on list results; and `uriTemplate` on resource templates.+Each bridged read emits a `FastMCPDeprecationWarning` pointing you at the snake_case name (`tools[0].input_schema` here). The bridge covers the fields users actually read: `inputSchema`/`outputSchema` on tools; `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` on tool annotations; `mimeType` on resources and content; `isError`/`structuredContent` on tool results; `nextCursor` on paginated results; `serverInfo`/`protocolVersion` on the initialize result; the sampling parameter fields (`systemPrompt`, `maxTokens`, `stopSequences`, `modelPreferences`, `toolChoice`); `requestedSchema` on elicitation parameters; `resourceTemplates` on the resource-template list result; `hasMore` on completions; and `uriTemplate` on resource templates.The bridge is controlled by the `mcp_camelcase_compat` setting, which defaults to on. Set it to `False` (or the environment variable `FASTMCP_MCP_CAMELCASE_COMPAT=false`) to turn the shims off, in which case only the snake_case names resolve:diff --git a/docs/getting-started/upgrading/from-low-level-sdk-v1.mdx b/docs/getting-started/upgrading/from-low-level-sdk-v1.mdxindex 48803f77d..a80ca279f 100644--- a/docs/getting-started/upgrading/from-low-level-sdk-v1.mdx+++ b/docs/getting-started/upgrading/from-low-level-sdk-v1.mdx@@ -233,7 +233,7 @@ When converting your `inputSchema` to Python type hints:With the `Server` class, tools return `list[types.TextContent | types.ImageContent | ...]`. In FastMCP, return plain Python values โ strings, numbers, dicts, lists, dataclasses, Pydantic models โ and serialization is handled for you.-For images or other non-text content, FastMCP provides helpers:+For images or other non-text content, FastMCP provides helpers. `Image` takes a file path, or raw bytes with `data=` and `format=`:```pythonfrom fastmcp import FastMCP@@ -242,10 +242,9 @@ from fastmcp.utilities.types import Imagemcp = FastMCP("media")@mcp.tool-def create_chart(data: list[float]) -> Image:- """Generate a chart from data."""- png_bytes = generate_chart(data) # your logic- return Image(data=png_bytes, format="png")+def latest_chart() -> Image:+ """Return the most recent chart."""+ return Image(path="chart.png")```## Resources@@ -470,7 +469,7 @@ async def process_data(ctx: Context) -> str:</CodeGroup>-The `Context` object provides logging (`ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`), progress reporting (`ctx.report_progress()`), resource subscriptions, session state, and more. See [Context](/servers/context) for the full API.+The `Context` object provides logging (`ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`), progress reporting (`ctx.report_progress()`), session state, and more. See [Context](/servers/context) for the full API.## Errorsdiff --git a/docs/getting-started/upgrading/from-low-level-sdk-v2.mdx b/docs/getting-started/upgrading/from-low-level-sdk-v2.mdxindex 0cfaca684..61ac643ec 100644--- a/docs/getting-started/upgrading/from-low-level-sdk-v2.mdx+++ b/docs/getting-started/upgrading/from-low-level-sdk-v2.mdx@@ -9,7 +9,7 @@ If your server builds on the `mcp` package's low-level `Server` class as SDK v2The core idea: instead of describing your tools to the SDK and then separately implementing them, you write ordinary Python functions and let FastMCP derive the protocol layer from your code. Type hints become JSON Schema. Docstrings become descriptions. Return values are serialized automatically. The dispatch you wrote to route a call by name, and the schemas you wrote by hand to describe it, both disappear.-Migrating from SDK v2 is the most direct of the four upgrade paths, because you and FastMCP already share a protocol layer. FastMCP 4 is built on SDK v2, so `mcp_types` imports keep working, field names are already snake_case, and the era negotiation you get is the one you have. Almost nothing about the wire changes โ the one exception is [argument strictness](#stricter-arguments), covered below.+Migrating from the low-level SDK v2 is more direct than migrating from v1, because you and FastMCP already share a protocol layer. FastMCP 4 is built on SDK v2, so `mcp_types` imports keep working, field names are already snake_case, and the era negotiation you get is the one you have. Almost nothing about the wire changes โ the one exception is [argument strictness](#stricter-arguments), covered below.<Note>On SDK v1's decorator-registered `Server` โ `@server.list_tools()`, `@server.call_tool()` โ instead? See [Upgrading from the Low-Level SDK v1](/getting-started/upgrading/from-low-level-sdk-v1), where the before-and-after code matches that API.@@ -51,7 +51,7 @@ TYPES THAT DISAPPEAR FROM YOUR CODECONTEXT AND SIDE CHANNELS- `ctx.session.send_log_message(...)` โ `ctx.info()` / `ctx.debug()` / `ctx.warning()` / `ctx.error()` on a `fastmcp.Context` parameter- `ctx.session.report_progress(...)` โ `ctx.report_progress()`-- `ctx.request_id`, `ctx.meta`, `ctx.protocol_version` โ these live on `ctx.request_context` in FastMCP (`ctx.request_context.request_id`, and so on); note that `ctx.protocol_version` directly on the Context does not exist+- `ctx.meta`, `ctx.protocol_version` โ these live on `ctx.request_context` in FastMCP (`ctx.request_context.meta`, `ctx.request_context.protocol_version`); `ctx.protocol_version` directly on the Context does not exist. `ctx.request_id` is on FastMCP's Context as well, converted to a `str`- `ctx.params` โ no equivalent, and none is needed: the raw request params were how a low-level handler read the tool's arguments, and those are now the decorated function's typed parameters. `ctx.request_context.params` does NOT exist and raises AttributeError.- Direct `ctx.session` use for anything else โ `Context.session` exists in FastMCP too and returns the same raw SDK session, so this still works; prefer a `Context` method where one exists, and note the remaining uses as SDK-coupled@@ -212,7 +212,7 @@ Constraints carry over too. A schema with `"minimum"` and `"maximum"` becomes a### Return Values-The low-level class requires tools to return a `CallToolResult` wrapping a list of content blocks. FastMCP takes the value itself โ strings, numbers, dicts, lists, dataclasses, Pydantic models โ and handles both the content block and the structured output. For images and audio, FastMCP provides wrapper types that carry the format:+The low-level class requires tools to return a `CallToolResult` wrapping a list of content blocks. FastMCP takes the value itself โ strings, numbers, dicts, lists, dataclasses, Pydantic models โ and handles both the content block and the structured output. For images and audio, FastMCP provides wrapper types that carry the format. Each takes a file path, or raw bytes with `data=` and `format=`:```pythonfrom fastmcp import FastMCP@@ -222,10 +222,9 @@ mcp = FastMCP("media")@mcp.tool-def create_chart(data: list[float]) -> Image:- """Generate a chart from data."""- png_bytes = render_png(data) # your logic- return Image(data=png_bytes, format="png")+def latest_chart() -> Image:+ """Return the most recent chart."""+ return Image(path="chart.png")```When you need full control over the wire result โ multiple content blocks, or structured content that differs from the content blocks โ return a `ToolResult` from `fastmcp.tools` instead.diff --git a/docs/getting-started/upgrading/from-mcp-sdk-v1.mdx b/docs/getting-started/upgrading/from-mcp-sdk-v1.mdxindex 84f792664..b760ee20a 100644--- a/docs/getting-started/upgrading/from-mcp-sdk-v1.mdx+++ b/docs/getting-started/upgrading/from-mcp-sdk-v1.mdx@@ -75,16 +75,15 @@ THE IMPORT (every server needs this)CONSTRUCTOR ARGUMENTS THAT MOVED (all raise TypeError)- moved to run()/http_app(), and FastMCP names them in the error: host, port, log_level, debug, sse_path, message_path, streamable_http_path, json_response, stateless_http-- moved but rejected with only a generic "unexpected keyword argument", so flag these explicitly: `event_store=` (โ `http_app(event_store=...)`; dropping it silently disables streamable-HTTP resumability), `mount_path=` (โ `http_app(path=...)`), `transport=` (โ `run(transport=...)`), `transport_security=` (โ host/origin settings on `http_app()`), `warn_on_duplicate_tools/_resources/_prompts=` (โ one `on_duplicate=`), `dependencies=` (โ a fastmcp.json file)+- moved but rejected with only a generic "unexpected keyword argument", so flag these explicitly: `event_store=` (โ `http_app(event_store=...)`; dropping it silently disables streamable-HTTP resumability), `retry_interval=` and `session_idle_timeout=` (โ the same keywords on `http_app()`), `mount_path=` (โ `http_app(path=...)`), `transport=` (โ `run(transport=...)`), `transport_security=` (โ host/origin settings on `http_app()`), `warn_on_duplicate_tools/_resources/_prompts=` (โ one `on_duplicate=`), `dependencies=` (โ a fastmcp.json file)- `name`, `instructions`, `website_url`, `icons`, `tools`, `lifespan` carry over unchanged- note when reporting: FastMCP names the streamable HTTP transport "http", not "streamable-http"CONTEXT METHODS WITH CHANGED SIGNATURES (compile fine, fail at runtime)-- `ctx.log(level, data)` โ `ctx.log(message, level=...)`, message first-- `ctx.info(data)` / `debug` / `warning` / `error` โ take a str message, not arbitrary JSON-serializable data+- `ctx.log(level, message)` โ `ctx.log(message, level=...)`, message first- `ctx.elicit(..., schema=Model)` โ `response_type=Model`- `ctx.read_resource(uri)` โ returns a `ResourceResult`; read `.contents` rather than iterating the return value-- `ctx.report_progress`, `ctx.request_id`, `ctx.client_id` are unchanged+- `ctx.info` / `debug` / `warning` / `error`, `ctx.report_progress`, `ctx.request_id`, `ctx.client_id` are unchangedAUTHENTICATION (the one case where the single import change is NOT enough)- `token_verifier=` and `auth_server_provider=` โ both raise TypeError on FastMCP 4@@ -100,9 +99,6 @@ OTHER mcp.* IMPORTS- `from mcp.server.stdio import stdio_server` and any transport boilerplate around it- `mcp.types.TextContent` / `ImageContent` used to wrap tool return values โ FastMCP has friendlier equivalents, so prefer those over keeping the raw protocol types-DECORATOR RETURN VALUES-- any code reading `.name`, `.description`, or other component attributes off a `@mcp.tool` / `@mcp.resource` / `@mcp.prompt` decorated function. Decorators return the original function now.-For each item found, show the original line, name what changed, and give the corrected code from the guide. If the only change needed is the import, say so plainly rather than manufacturing work.</Prompt>@@ -133,6 +129,7 @@ A second group is rejected with only a generic "unexpected keyword argument" and| SDK v1 `FastMCP(...)` | FastMCP 4 ||---|---|| `event_store=` | `mcp.http_app(event_store=...)` |+| `retry_interval=`, `session_idle_timeout=` | the same keywords on `mcp.http_app()` || `mount_path=` | `mcp.http_app(path=...)` || `transport=` | `mcp.run(transport=...)` || `transport_security=` | `host_origin_protection=`, `allowed_hosts=`, `allowed_origins=` on `http_app()` |@@ -168,16 +165,15 @@ See [Authentication](/servers/auth/authentication) for the full set and their co### Context Methods-`from fastmcp import Context` gets you the injected context object, but four of its methods took a different shape in FastMCP 1.0, and a bare import swap leaves calls that compile and then fail:+`from fastmcp import Context` gets you the injected context object, but three of its methods took a different shape in FastMCP 1.0, and a bare import swap leaves calls that compile and then fail:| SDK v1 | FastMCP 4 ||---|---|-| `ctx.log(level, data)` | `ctx.log(message, level=...)` โ message is first now |-| `ctx.info(data)` and its `debug`/`warning`/`error` siblings | take a `str` message, where v1 accepted any JSON-serializable value |+| `ctx.log(level, message)` | `ctx.log(message, level=...)` โ message is first now || `ctx.elicit(message, schema=Model)` | `ctx.elicit(message, response_type=Model)` || `ctx.read_resource(uri)` | returns a `ResourceResult`; the payload is under `.contents` rather than being iterable directly |-`ctx.report_progress()`, `ctx.request_id`, and `ctx.client_id` are unchanged.+`ctx.info()` and its `debug`/`warning`/`error` siblings, `ctx.report_progress()`, `ctx.request_id`, and `ctx.client_id` are unchanged.### Prompts@@ -229,7 +225,7 @@ For protocol types without a FastMCP equivalent, import them from `mcp_types` di### Decorated Functions-In FastMCP 1.0, `@mcp.tool` replaced your function with a `FunctionTool` object. Now decorators return your original function unchanged, so decorated functions stay callable for testing, reuse, and composition:+Decorators return your original function unchanged, as they did in FastMCP 1.0, so decorated functions stay callable for testing, reuse, and composition. FastMCP 1.0 required the call form, `@mcp.tool()`; FastMCP accepts that and the bare `@mcp.tool` alike:```pythonfrom fastmcp import FastMCP@@ -245,7 +241,7 @@ def greet(name: str) -> str:assert greet("World") == "Hello, World!"```-Code that reads `.name`, `.description`, or other component attributes off the decorated result needs updating. This is uncommon โ most servers never touch the tool object. When you do need the component itself, reach it through the server with `await mcp.get_tool("greet")`.+When you need the component object itself, reach it through the server with `await mcp.get_tool("greet")`.## Verifying the Upgrade@@ -255,7 +251,7 @@ Run your server the way you always have. To confirm every component came across,fastmcp inspect my_server.py```-The output lists every tool, resource, template, and prompt your server exposes, so a component that failed to register shows up here rather than at the first client call.+The summary counts the tools, resources, templates, and prompts your server exposes, and `--format fastmcp` prints each one in full, so a component that failed to register shows up here rather than at the first client call.## Looking Aheaddiff --git a/docs/getting-started/upgrading/from-mcp-sdk-v2.mdx b/docs/getting-started/upgrading/from-mcp-sdk-v2.mdxindex 0df190b55..0588edf67 100644--- a/docs/getting-started/upgrading/from-mcp-sdk-v2.mdx+++ b/docs/getting-started/upgrading/from-mcp-sdk-v2.mdx@@ -63,7 +63,7 @@ CONSTRUCTOR ARGUMENTS THAT DO NOT CARRY OVER- `cache_hints=`- `extensions=`- `tools=[...]` (rare โ the SDK's `Tool` type is not exported): FastMCP takes plain callables, so pass the underlying functions-These raise TypeError, most naming their replacement. `name`, `version`, `instructions`, `icons`, `website_url`, `lifespan`, `resource_security`, and `request_state_security` carry over unchanged.+Passing any of these raises TypeError, except `auth=`: the keyword survives, and an SDK `AuthSettings` value fails later, with an AttributeError when the server builds its HTTP app. Only `debug=` and `log_level=` get an error naming the replacement. `name`, `version`, `instructions`, `icons`, `website_url`, `lifespan`, `resource_security`, and `request_state_security` carry over unchanged.CONTEXT โ these ten properties do NOT exist on FastMCP's Context and raise AttributeError if you only swap the import:- `ctx.mcp_server` โ `ctx.fastmcp`@@ -79,7 +79,7 @@ These four exist on both but with DIFFERENT signatures, so a bare import swap co- `ctx.elicit(message, schema=Model)` โ `ctx.elicit(message, response_type=Model)` โ the keyword was renamed- `ctx.read_resource(uri)` โ still takes a URI, but returns a `ResourceResult` whose payload is under `.contents`, where the SDK returned an iterable of content objects directly. Code that iterates or indexes the return value needs updating.-Genuinely unchanged: `report_progress`, `request_id`, `client_id`, `input_responses`, `request_state`, `session`, and `request_context`.+Genuinely unchanged: `report_progress`, `request_id`, `client_id`, `input_responses`, `request_state`, `close_sse_stream`, `session`, and `request_context`.RESOLVERS โ the one part that is not a rename, so check for it first- any `Annotated[T, Resolve(fn)]` parameter, and the resolvers behind it@@ -209,7 +209,7 @@ if __name__ == "__main__":## Constructor Arguments-`FastMCP()` describes your server's identity and behavior; how it gets deployed is decided when you serve it. Several `MCPServer` constructor arguments move accordingly, and each raises a `TypeError` naming its replacement rather than being silently ignored.+`FastMCP()` describes your server's identity and behavior; how it gets deployed is decided when you serve it. Several `MCPServer` constructor arguments move accordingly. Each raises a `TypeError` rather than being silently ignored, but only `debug=` and `log_level=` get an error naming the replacement; the rest fail with a generic "unexpected keyword argument", so use the table below.`name`, `version`, `instructions`, `icons`, `website_url`, `lifespan`, `resource_security`, and `request_state_security` all mean what they meant before. The rest map like this:@@ -243,10 +243,11 @@ Renaming `streamable_http_app()` to `http_app()` is only mechanical for a call w| `streamable_http_app(streamable_http_path=...)` | `http_app(path=...)` || `sse_app(sse_path=...)` | `http_app(path=..., transport="sse")` || `sse_app(message_path=...)` | no equivalent |+| `max_request_body_size=`, `max_sessions=` | no equivalent || `transport_security=TransportSecuritySettings(...)` | `host_origin_protection=`, `allowed_hosts=`, `allowed_origins=` || `host=...` | pass to `mcp.run(host=...)` instead |-`json_response`, `stateless_http`, `event_store`, and `retry_interval` keep their names. See [Deploying HTTP servers](/deployment/http) for the host and origin settings.+`json_response`, `stateless_http`, `event_store`, `retry_interval`, and `session_idle_timeout` keep their names. See [Deploying HTTP servers](/deployment/http) for the host and origin settings.### Stricter Argumentsdiff --git a/docs/getting-started/whats-new.mdx b/docs/getting-started/whats-new.mdxindex 1ef2b848e..83d9c1fb6 100644--- a/docs/getting-started/whats-new.mdx+++ b/docs/getting-started/whats-new.mdx@@ -127,7 +127,7 @@ The default in-memory state store is process-local. To preserve state across resLong-running tools create a different kind of state problem: holding a request open for several minutes invites timeouts and leaves the user unable to tell whether work is progressing. Background tasks accept the call and return a handle immediately, then let the client poll while work proceeds asynchronously.-FastMCP implements the `io.modelcontextprotocol/tasks` extension in the optional `fastmcp-tasks` package. The authoring API remains `@mcp.tool(task=True)`, backed by [Docket](https://github.com/chrisguidry/docket):+FastMCP implements the `io.modelcontextprotocol/tasks` extension in the optional `fastmcp-tasks` package, installed with `pip install "fastmcp[tasks]"`. The authoring API remains `@mcp.tool(task=True)`, backed by [Docket](https://github.com/chrisguidry/docket):```pythonimport asynciodiff --git a/docs/more/settings.mdx b/docs/more/settings.mdxindex 88fbb715c..24e05524f 100644--- a/docs/more/settings.mdx+++ b/docs/more/settings.mdx@@ -54,7 +54,7 @@ These control how the server listens when running with an HTTP transport.| `FASTMCP_STREAMABLE_HTTP_PATH` | `str` | `/mcp` | Path for Streamable HTTP endpoint. || `FASTMCP_STATELESS_HTTP` | `bool` | `false` | Enable stateless HTTP mode (new transport per request). Useful for multi-worker deployments. || `FASTMCP_JSON_RESPONSE` | `bool` | `false` | Use JSON responses instead of SSE for Streamable HTTP. |-| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | `bool \| "auto"` | `false` | Validate `Host` and browser `Origin` headers for Streamable HTTP and SSE requests. `auto` protects localhost-bound servers and explicit host/origin allowlists. `false` disables this guard and FastMCP's DNS-rebinding protection for the endpoint. |+| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | `bool \| "auto"` | `false` | Validate `Host` and browser `Origin` headers for Streamable HTTP and SSE requests. `true` validates every request; `auto` protects localhost-bound servers and explicit host/origin allowlists. `false` disables this guard and FastMCP's DNS-rebinding protection for the endpoint. || `FASTMCP_HTTP_ALLOWED_HOSTS` | `list[str] \| null` | `null` | Additional trusted hostnames when Host and Origin protection is enabled. Use a JSON array, such as `["mcp.example.com"]`. || `FASTMCP_HTTP_ALLOWED_ORIGINS` | `list[str] \| null` | `null` | Browser origins trusted when Host and Origin protection is enabled. Configure CORS separately for cross-origin browser reads. Use a JSON array, such as `["https://app.example.com"]`. || `FASTMCP_HTTP_SESSION_IDLE_TIMEOUT` | `float \| "auto" \| "none"` | `"auto"` | Seconds a stateful Streamable HTTP session may remain idle before it is terminated. `"auto"` uses the MCP SDK's default: 1800 seconds (30 minutes) in SDK 2.2, no timeout in earlier versions. Set a positive number to override it, or `none` to disable it. |@@ -79,7 +79,7 @@ to release that capacity. Stateless HTTP does not use the session pool.|---|---|---|---|| `FASTMCP_CLIENT_INIT_TIMEOUT` | `float \| None` | None | Timeout in seconds for the client initialization handshake. Set to `0` or leave unset to disable. || `FASTMCP_CLIENT_DISCONNECT_TIMEOUT` | `float` | `5` | Maximum time in seconds to wait for a clean disconnect before giving up. |-| `FASTMCP_TASKS_CLIENT_POLL_INTERVAL` | `float` | `0.5` | Ceiling in seconds for the fallback poll backoff while waiting on a [background task](/servers/tasks). Requires the `fastmcp-tasks` package. Applies **only** when the server does not advertise its own `pollInterval`: in that case `Task.wait()` starts polling fast (~20ms) and doubles up to this ceiling rather than polling at a fixed cadence. When the server advertises a `pollInterval`, that interval is honored exactly and this setting is ignored. |+| `FASTMCP_TASKS_CLIENT_POLL_INTERVAL` | `float` | `0.5` | Ceiling in seconds for the fallback poll backoff while waiting on a [background task](/servers/tasks). Requires the `fastmcp-tasks` package. Applies **only** when the server does not advertise its own `pollIntervalMs`: in that case `Task.wait()` starts polling fast (~20ms) and doubles up to this ceiling rather than polling at a fixed cadence. When the server advertises a `pollIntervalMs`, that interval is honored exactly and this setting is ignored. || `FASTMCP_CLIENT_RAISE_FIRST_EXCEPTIONGROUP_ERROR` | `bool` | `true` | When an `ExceptionGroup` is raised, re-raise the first error directly instead of the group. Simplifies debugging but may mask secondary errors. |## CLI & Display@@ -87,7 +87,7 @@ to release that capacity. Stateless HTTP does not use the session pool.| Environment Variable | Type | Default | Description ||---|---|---|---|| `FASTMCP_SHOW_SERVER_BANNER` | `bool` | `true` | Show the server banner on startup. Also controllable via `--no-banner` or `server.run(show_banner=False)`. |-| `FASTMCP_CHECK_FOR_UPDATES` | `Literal["stable", "prerelease", "off"]` | `stable` | Update checking on CLI startup. `stable` checks stable releases only, `prerelease` includes pre-releases, `off` disables checking. |+| `FASTMCP_CHECK_FOR_UPDATES` | `Literal["stable", "prerelease", "off"]` | `stable` | Update checking when the server banner is shown and when `fastmcp version` runs. `stable` checks stable releases only, `prerelease` includes pre-releases, `off` disables checking. || `FASTMCP_OAUTH_ENCRYPTION_KEY` | `str \| None` | None | Fernet key for [encrypted CLI OAuth storage](/cli/overview#mcp-server-authentication). An unset or empty value uses memory only. |## Telemetry@@ -110,16 +110,14 @@ These control FastMCP's SSRF protection for the outbound fetches it makes duringBy default, FastMCP protects its OAuth and JWKS fetches against [SSRF](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery) by resolving the target hostname, rejecting any address that maps to a private, loopback, link-local, or reserved IP, and then pinning the connection to that validated IP.-Setting `FASTMCP_SSRF_TRUST_PROXY=true` disables FastMCP's local DNS/IP checks and connection pinning. This reduces SSRF protection unless the configured proxy enforces equivalent destination restrictions. FastMCP verifies that a proxy is configured, but does not verify its security policy.-This breaks when a corporate `CONNECT` proxy is the only egress path: the container often cannot resolve external DNS at all (only the proxy can), and even when it can, pinning to the IP makes TLS verification fail because public certificates list hostnames, not IP addresses.-Set `FASTMCP_SSRF_TRUST_PROXY=true` when a trusted proxy is your mandated egress. FastMCP then skips DNS resolution and the IP blocklist entirely and makes a single request to the hostname URL, explicitly routed through the proxy named by the standard `HTTPS_PROXY` / `ALL_PROXY` environment variables (checked in that order). The HTTPS-only and hostname checks still apply.+Set `FASTMCP_SSRF_TRUST_PROXY=true` when a trusted proxy is your mandated egress. FastMCP then skips DNS resolution, the IP blocklist, and connection pinning, and makes a single request to the hostname URL through the proxy named by the standard `HTTPS_PROXY` / `ALL_PROXY` environment variables (checked in that order). The HTTPS-only and hostname checks still apply.<Warning>-This is a deliberate trust shift: the IP blocklist cannot be enforced through a proxy (the proxy does its own DNS, so an address FastMCP resolved is not the one the proxy dials). Only enable it when the proxy itself is trusted to mediate egress.+This setting shifts SSRF protection to the proxy. The IP blocklist cannot be enforced through a proxy, because the proxy does its own DNS, and FastMCP verifies that a proxy is configured but not what its policy allows. Enable it only when the proxy enforces equivalent destination restrictions.-FastMCP reads the proxy URL from the environment and passes it to the HTTP client explicitly, with the client's own environment-based proxy routing turned off โ so the request either goes through that exact proxy or fails outright, with no routing decision left for the client to make on its own. One consequence: `NO_PROXY` is **not honored** in this mode. A host that `NO_PROXY` would otherwise exclude is still routed through the configured proxy rather than fetched direct with the IP blocklist disabled โ the safer of the two options, since the blocklist cannot apply to a direct fetch here anyway. If you set `FASTMCP_SSRF_TRUST_PROXY=true` but neither `HTTPS_PROXY` nor `ALL_PROXY` is present in the server process's environment (an `HTTP_PROXY` alone never routes these HTTPS-only fetches), the request would otherwise go out **direct with the IP blocklist disabled** โ no SSRF protection at all. Rather than send it, FastMCP refuses the fetch and raises `SSRFError` with an actionable message. The contract is crisp: proxy-trust mode delegates SSRF protection to the proxy, and with no proxy configured the fetch cannot proceed. Enable this setting only together with an active proxy that routes your auth endpoints.+FastMCP passes the proxy URL to the HTTP client explicitly, so the request goes through that proxy or fails. `NO_PROXY` is **not honored** in this mode: a host it would exclude still goes through the proxy instead of direct with no blocklist. If neither `HTTPS_PROXY` nor `ALL_PROXY` is set in the server process's environment (`HTTP_PROXY` alone never routes these HTTPS-only fetches), FastMCP refuses the fetch and raises `SSRFError`.</Warning>## Advanced@@ -128,4 +126,4 @@ FastMCP reads the proxy URL from the environment and passes it to the HTTP clien|---|---|---|---|| `FASTMCP_HOME` | `Path` | Platform default | Data directory for FastMCP. Defaults to the platform-specific user data directory. || `FASTMCP_ENV_FILE` | `str` | `.env` | Path to the `.env` file to load settings from. Must be set as an environment variable (see above). |-| `FASTMCP_TEST_MODE` | `bool` | `false` | Enable test mode. |+| `FASTMCP_TEST_MODE` | `bool` | `false` | Lower the key-derivation cost FastMCP uses for JWT signing keys built from low-entropy secrets, so test suites run faster. Never enable it in production. |diff --git a/docs/patterns/contrib.mdx b/docs/patterns/contrib.mdxindex 648cf8722..c5af82f17 100644--- a/docs/patterns/contrib.mdx+++ b/docs/patterns/contrib.mdx@@ -16,10 +16,10 @@ The available modules can be viewed in the [contrib directory](https://github.co## Usage-To use a contrib module, import it from the `fastmcp.contrib` package:+To use a contrib module, import it from its subpackage under `fastmcp.contrib`. For example, the `mcp_mixin` module:-```python test="skip"-from fastmcp.contrib import my_module+```python+from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool```## Important Considerations