fastmcp 2.11.0__tar.gz → 2.11.2__tar.gz

{fastmcp-2.11.0 → fastmcp-2.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.11.0
+Version: 2.11.2
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/changelog.mdx

@@ -2,6 +2,111 @@
 icon: "list-check"
 ---
 
+<Update label="v2.11.0" description="2025-08-01">
+
+## [v2.11.0: Auth to a Good Start](https://github.com/jlowin/fastmcp/releases/tag/v2.11.0)
+
+FastMCP 2.11 doubles down on what developers need most: speed and simplicity. This massive release delivers significant performance improvements and a dramatically better developer experience.
+
+🔐 **Enterprise-Ready Authentication** brings comprehensive OAuth 2.1 support with WorkOS's AuthKit integration. The new AuthProvider interface leverages MCP's support for separate resource and authorization servers, handling API keys and remote authentication with Dynamic Client Registration. AuthKit integration means you can plug into existing enterprise identity systems without rebuilding your auth stack, setting the stage for plug-and-play auth that doesn't require users to become security experts overnight.
+
+⚡ The **Experimental OpenAPI Parser** delivers dramatic performance improvements through single-pass schema processing and optimized memory usage. OpenAPI integrations are now significantly faster, with cleaner, more maintainable code. _(Note: the experimental parser is disabled by default, set `FASTMCPEXPERIMENTALENABLENEWOPENAPIPARSER=1` to enable it. A message will be shown to all users on the legacy parser encouraging them to try the new one before it becomes the default.)_
+
+🧠 **Context State Management** finally gives you persistent state across tool calls with a simple dict interface, while enhanced meta support lets you expose rich component metadata to clients. Combined with improved type annotations, string-based argument descriptions, and UV transport support, this release makes FastMCP feel more intuitive than ever.
+
+This release represents a TON of community contributions and sets the foundation for even more ambitious features ahead.
+
+## What's Changed
+### New Features 🎉
+* Introduce experimental OpenAPI parser with improved performance and maintainability by [@jlowin](https://github.com/jlowin) in [#1209](https://github.com/jlowin/fastmcp/pull/1209)
+* Add state dict to Context (#1118) by [@mukulmurthy](https://github.com/mukulmurthy) in [#1160](https://github.com/jlowin/fastmcp/pull/1160)
+* Expose FastMCP tags to clients via component `meta` dict by [@jlowin](https://github.com/jlowin) in [#1281](https://github.com/jlowin/fastmcp/pull/1281)
+* Add _fastmcp meta namespace by [@jlowin](https://github.com/jlowin) in [#1290](https://github.com/jlowin/fastmcp/pull/1290)
+* Add TokenVerifier protocol support alongside existing OAuthProvider authentication by [@jlowin](https://github.com/jlowin) in [#1297](https://github.com/jlowin/fastmcp/pull/1297)
+* Add comprehensive OAuth 2.1 authentication system with WorkOS integration by [@jlowin](https://github.com/jlowin) in [#1327](https://github.com/jlowin/fastmcp/pull/1327)
+### Enhancements 🔧
+* [🐶] Transform MCP Server Tools by [@strawgate](https://github.com/strawgate) in [#1132](https://github.com/jlowin/fastmcp/pull/1132)
+* Add --python, --project, and --with-requirements options to CLI commands by [@jlowin](https://github.com/jlowin) in [#1190](https://github.com/jlowin/fastmcp/pull/1190)
+* Support `fastmcp run mcp.json` by [@strawgate](https://github.com/strawgate) in [#1138](https://github.com/jlowin/fastmcp/pull/1138)
+* Support from __future__ import annotations by [@jlowin](https://github.com/jlowin) in [#1199](https://github.com/jlowin/fastmcp/pull/1199)
+* Optimize OpenAPI parser performance with single-pass schema processing by [@jlowin](https://github.com/jlowin) in [#1214](https://github.com/jlowin/fastmcp/pull/1214)
+* Log tool name on transform validation error by [@strawgate](https://github.com/strawgate) in [#1238](https://github.com/jlowin/fastmcp/pull/1238)
+* Refactor `get_http_request` and `context.session_id` by [@hopeful0](https://github.com/hopeful0) in [#1242](https://github.com/jlowin/fastmcp/pull/1242)
+* Support creating tool argument descriptions from string annotations by [@jlowin](https://github.com/jlowin) in [#1255](https://github.com/jlowin/fastmcp/pull/1255)
+* feat: Add Annotations support for resources and resource templates by [@chughtapan](https://github.com/chughtapan) in [#1260](https://github.com/jlowin/fastmcp/pull/1260)
+* Add UV Transport by [@strawgate](https://github.com/strawgate) in [#1270](https://github.com/jlowin/fastmcp/pull/1270)
+* Improve OpenAPI-to-JSONSchema conversion utilities by [@jlowin](https://github.com/jlowin) in [#1283](https://github.com/jlowin/fastmcp/pull/1283)
+* Ensure proxy components forward meta dicts by [@jlowin](https://github.com/jlowin) in [#1282](https://github.com/jlowin/fastmcp/pull/1282)
+* fix: server argument passing in CLI run command by [@chughtapan](https://github.com/chughtapan) in [#1293](https://github.com/jlowin/fastmcp/pull/1293)
+* Add meta support to tool transformation utilities by [@jlowin](https://github.com/jlowin) in [#1295](https://github.com/jlowin/fastmcp/pull/1295)
+* feat: Allow Resource Metadata URL as field in OAuthProvider by [@dacamposol](https://github.com/dacamposol) in [#1287](https://github.com/jlowin/fastmcp/pull/1287)
+* Use a simple overwrite instead of a merge for meta by [@jlowin](https://github.com/jlowin) in [#1296](https://github.com/jlowin/fastmcp/pull/1296)
+* Remove unused TimedCache by [@strawgate](https://github.com/strawgate) in [#1303](https://github.com/jlowin/fastmcp/pull/1303)
+* refactor: standardize logging usage across OpenAPI utilities by [@chi2liu](https://github.com/chi2liu) in [#1322](https://github.com/jlowin/fastmcp/pull/1322)
+* perf: optimize OpenAPI parsing by reducing dict copy operations by [@chi2liu](https://github.com/chi2liu) in [#1321](https://github.com/jlowin/fastmcp/pull/1321)
+* Structured client-side logging by [@cjermain](https://github.com/cjermain) in [#1326](https://github.com/jlowin/fastmcp/pull/1326)
+### Fixes 🐞
+* fix: preserve def reference when referenced in allOf / oneOf / anyOf by [@algirdasci](https://github.com/algirdasci) in [#1208](https://github.com/jlowin/fastmcp/pull/1208)
+* fix: add type hint to custom_route decorator by [@zzstoatzz](https://github.com/zzstoatzz) in [#1210](https://github.com/jlowin/fastmcp/pull/1210)
+* chore: typo by [@richardkmichael](https://github.com/richardkmichael) in [#1216](https://github.com/jlowin/fastmcp/pull/1216)
+* fix: handle non-string $ref values in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1217](https://github.com/jlowin/fastmcp/pull/1217)
+* Skip repeated type conversion and validation in proxy client elicitation handler by [@chughtapan](https://github.com/chughtapan) in [#1222](https://github.com/jlowin/fastmcp/pull/1222)
+* Ensure default fields are not marked nullable by [@jlowin](https://github.com/jlowin) in [#1224](https://github.com/jlowin/fastmcp/pull/1224)
+* Fix stateful proxy client mixing in multi-proxies sessions by [@hopeful0](https://github.com/hopeful0) in [#1245](https://github.com/jlowin/fastmcp/pull/1245)
+* Fix invalid async context manager usage in proxy documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#1246](https://github.com/jlowin/fastmcp/pull/1246)
+* fix: experimental FastMCPOpenAPI server lost headers in request when __init__(client with headers) by [@itaru2622](https://github.com/itaru2622) in [#1254](https://github.com/jlowin/fastmcp/pull/1254)
+* Fix typing, add tests for tool call middleware by [@jlowin](https://github.com/jlowin) in [#1269](https://github.com/jlowin/fastmcp/pull/1269)
+* Fix: prune hidden parameter defs by [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) in [#1257](https://github.com/jlowin/fastmcp/pull/1257)
+* Fix nullable field handling in OpenAPI to JSON Schema conversion by [@jlowin](https://github.com/jlowin) in [#1279](https://github.com/jlowin/fastmcp/pull/1279)
+* Ensure fastmcp run supports v1 servers by [@jlowin](https://github.com/jlowin) in [#1332](https://github.com/jlowin/fastmcp/pull/1332)
+### Breaking Changes 🛫
+* Change server flag to --name by [@jlowin](https://github.com/jlowin) in [#1248](https://github.com/jlowin/fastmcp/pull/1248)
+### Docs 📚
+* Remove unused import from FastAPI integration documentation by [@mariotaddeucci](https://github.com/mariotaddeucci) in [#1194](https://github.com/jlowin/fastmcp/pull/1194)
+* Update fastapi docs by [@jlowin](https://github.com/jlowin) in [#1198](https://github.com/jlowin/fastmcp/pull/1198)
+* Add docs for context state management by [@jlowin](https://github.com/jlowin) in [#1227](https://github.com/jlowin/fastmcp/pull/1227)
+* Permit.io integration docs by [@orweis](https://github.com/orweis) in [#1226](https://github.com/jlowin/fastmcp/pull/1226)
+* Update docs to reflect sync tools by [@jlowin](https://github.com/jlowin) in [#1234](https://github.com/jlowin/fastmcp/pull/1234)
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1235](https://github.com/jlowin/fastmcp/pull/1235)
+* Update SDK docs by [@jlowin](https://github.com/jlowin) in [#1236](https://github.com/jlowin/fastmcp/pull/1236)
+* Update --name flag documentation for Cursor/Claude by [@adam-conway](https://github.com/adam-conway) in [#1239](https://github.com/jlowin/fastmcp/pull/1239)
+* Add annotations docs by [@jlowin](https://github.com/jlowin) in [#1268](https://github.com/jlowin/fastmcp/pull/1268)
+* Update openapi/fastapi URLs README.md by [@jbn](https://github.com/jbn) in [#1278](https://github.com/jlowin/fastmcp/pull/1278)
+* Add 2.11 version badge for state management by [@jlowin](https://github.com/jlowin) in [#1289](https://github.com/jlowin/fastmcp/pull/1289)
+* Add meta parameter support to tools, resources, templates, and prompts decorators by [@jlowin](https://github.com/jlowin) in [#1294](https://github.com/jlowin/fastmcp/pull/1294)
+* docs: update get_state and set_state references by [@Maxi91f](https://github.com/Maxi91f) in [#1306](https://github.com/jlowin/fastmcp/pull/1306)
+* Add unit tests and docs for denying tool calls with middleware by [@jlowin](https://github.com/jlowin) in [#1333](https://github.com/jlowin/fastmcp/pull/1333)
+* Remove reference to stacked decorators by [@jlowin](https://github.com/jlowin) in [#1334](https://github.com/jlowin/fastmcp/pull/1334)
+* Eunomia authorization server can run embedded within the MCP server by [@tommitt](https://github.com/tommitt) in [#1317](https://github.com/jlowin/fastmcp/pull/1317)
+### Other Changes 🦾
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#1230](https://github.com/jlowin/fastmcp/pull/1230)
+* Logcapture addition to test_server file by [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) in [#1229](https://github.com/jlowin/fastmcp/pull/1229)
+* Add tests for headers with both legacy and experimental openapi parser by [@jlowin](https://github.com/jlowin) in [#1259](https://github.com/jlowin/fastmcp/pull/1259)
+* Small clean-up from MCP Tool Transform PR by [@strawgate](https://github.com/strawgate) in [#1267](https://github.com/jlowin/fastmcp/pull/1267)
+* Add test for proxy tags visibility by [@jlowin](https://github.com/jlowin) in [#1302](https://github.com/jlowin/fastmcp/pull/1302)
+* Add unit test for sampling with image messages by [@jlowin](https://github.com/jlowin) in [#1329](https://github.com/jlowin/fastmcp/pull/1329)
+* Remove redundant resource_metadata_url assignment by [@jlowin](https://github.com/jlowin) in [#1328](https://github.com/jlowin/fastmcp/pull/1328)
+* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#1331](https://github.com/jlowin/fastmcp/pull/1331)
+* Ensure validation errors are raised when masked by [@jlowin](https://github.com/jlowin) in [#1330](https://github.com/jlowin/fastmcp/pull/1330)
+
+## New Contributors
+* [@mariotaddeucci](https://github.com/mariotaddeucci) made their first contribution in [#1194](https://github.com/jlowin/fastmcp/pull/1194)
+* [@algirdasci](https://github.com/algirdasci) made their first contribution in [#1208](https://github.com/jlowin/fastmcp/pull/1208)
+* [@chughtapan](https://github.com/chughtapan) made their first contribution in [#1222](https://github.com/jlowin/fastmcp/pull/1222)
+* [@mukulmurthy](https://github.com/mukulmurthy) made their first contribution in [#1160](https://github.com/jlowin/fastmcp/pull/1160)
+* [@orweis](https://github.com/orweis) made their first contribution in [#1226](https://github.com/jlowin/fastmcp/pull/1226)
+* [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) made their first contribution in [#1229](https://github.com/jlowin/fastmcp/pull/1229)
+* [@adam-conway](https://github.com/adam-conway) made their first contribution in [#1239](https://github.com/jlowin/fastmcp/pull/1239)
+* [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) made their first contribution in [#1257](https://github.com/jlowin/fastmcp/pull/1257)
+* [@jbn](https://github.com/jbn) made their first contribution in [#1278](https://github.com/jlowin/fastmcp/pull/1278)
+* [@dacamposol](https://github.com/dacamposol) made their first contribution in [#1287](https://github.com/jlowin/fastmcp/pull/1287)
+* [@chi2liu](https://github.com/chi2liu) made their first contribution in [#1322](https://github.com/jlowin/fastmcp/pull/1322)
+* [@cjermain](https://github.com/cjermain) made their first contribution in [#1326](https://github.com/jlowin/fastmcp/pull/1326)
+
+**Full Changelog**: [v2.10.6...v2.11.0](https://github.com/jlowin/fastmcp/compare/v2.10.6...v2.11.0)
+
+</Update>
+
 <Update label="v2.10.6" description="2025-07-19">
 
 ## [v2.10.6: Hymn for the Weekend](https://github.com/jlowin/fastmcp/releases/tag/v2.10.6)

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/clients/auth/bearer.mdx

@@ -3,7 +3,6 @@ title: Bearer Token Authentication
 sidebarTitle: Bearer Auth
 description: Authenticate your FastMCP client with a Bearer token.
 icon: key
-tag: NEW
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx"

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/docs.json

@@ -95,8 +95,8 @@
                     "icon": "shield-check",
                     "pages": [
                       "servers/auth/authentication",
+                      "servers/auth/remote-oauth",
                       "servers/auth/token-verification",
-                      "servers/auth/remote-authentication",
                       "servers/auth/full-oauth-server"
                     ]
                   }
@@ -142,6 +142,7 @@
                 "group": "Integrations",
                 "pages": [
                   "integrations/anthropic",
+                  "integrations/authkit",
                   "integrations/chatgpt",
                   "integrations/claude-code",
                   "integrations/claude-desktop",
@@ -153,8 +154,7 @@
                   "integrations/openai",
                   "integrations/openapi",
                   "integrations/permit",
-                  "integrations/starlette",
-                  "integrations/authkit"
+                  "integrations/starlette"
                 ]
               },
               {
@@ -275,10 +275,12 @@
                         "pages": [
                           "python-sdk/fastmcp-server-auth-providers-__init__",
                           "python-sdk/fastmcp-server-auth-providers-bearer",
-                          "python-sdk/fastmcp-server-auth-providers-bearer_env",
-                          "python-sdk/fastmcp-server-auth-providers-in_memory"
+                          "python-sdk/fastmcp-server-auth-providers-in_memory",
+                          "python-sdk/fastmcp-server-auth-providers-jwt",
+                          "python-sdk/fastmcp-server-auth-providers-workos"
                         ]
-                      }
+                      },
+                      "python-sdk/fastmcp-server-auth-registry"
                     ]
                   },
                   "python-sdk/fastmcp-server-context",
@@ -315,7 +317,6 @@
                 "group": "fastmcp.utilities",
                 "pages": [
                   "python-sdk/fastmcp-utilities-__init__",
-                  "python-sdk/fastmcp-utilities-cache",
                   "python-sdk/fastmcp-utilities-cli",
                   "python-sdk/fastmcp-utilities-components",
                   "python-sdk/fastmcp-utilities-exceptions",

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/authkit.mdx

@@ -1,7 +1,7 @@
 ---
-title: WorkOS AuthKit 🤝 FastMCP
-sidebarTitle: WorkOS AuthKit
-description: Secure your FastMCP server with WorkOS AuthKit
+title: AuthKit 🤝 FastMCP
+sidebarTitle: AuthKit
+description: Secure your FastMCP server with AuthKit by WorkOS
 icon: shield-check
 tag: NEW
 ---
@@ -10,20 +10,20 @@ import { VersionBadge } from "/snippets/version-badge.mdx"
 
 <VersionBadge version="2.11.0" />
 
-This guide shows you how to secure your FastMCP server using **WorkOS AuthKit**, a complete authentication and user management solution. This integration uses the [**Remote Authentication**](/servers/auth/remote-authentication) pattern, where WorkOS handles user login and your FastMCP server validates the tokens.
+This guide shows you how to secure your FastMCP server using WorkOS's **AuthKit**, a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern, where AuthKit handles user login and your FastMCP server validates the tokens.
 
 
 ## Configuration
 ### Prerequisites
 
 Before you begin, you will need:
-1.  A **WorkOS Account** and a new **Project**.
-2.  An **AuthKit** instance configured within your WorkOS project.
+1.  A **[WorkOS Account](https://workos.com/)** and a new **Project**.
+2.  An **[AuthKit](https://www.authkit.com/)** instance configured within your WorkOS project.
 3.  Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`).
 
 ### Step 1: AuthKit Configuration
 
-In your WorkOS Dashboard, navigate to your AuthKit instance and configure the following settings:
+In your WorkOS Dashboard, enable AuthKit and configure the following settings:
 
 <Steps>
 <Step title="Enable Dynamic Client Registration">

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/chatgpt.mdx

@@ -3,7 +3,7 @@ title: ChatGPT 🤝 FastMCP
 sidebarTitle: ChatGPT
 description: Connect FastMCP servers to ChatGPT Deep Research
 icon: message-smile
-tag: NEW
+
 ---
 
 ChatGPT supports MCP servers through remote HTTP connections, allowing you to extend ChatGPT's capabilities with custom tools and knowledge from your FastMCP servers.

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/claude-code.mdx

@@ -3,7 +3,6 @@ title: Claude Code 🤝 FastMCP
 sidebarTitle: Claude Code
 description: Install and use FastMCP servers in Claude Code
 icon: message-smile
-tag: NEW
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx"

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/eunomia-authorization.mdx

@@ -3,7 +3,6 @@ title: Eunomia Authorization 🤝 FastMCP
 sidebarTitle: Eunomia Auth
 description: Add policy-based authorization to your FastMCP servers with Eunomia
 icon: shield-check
-tag: NEW
 ---
 
 Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Eunomia][eunomia-github] authorization middleware**.

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/mcp-json-configuration.mdx

@@ -1,6 +1,6 @@
 ---
 title: MCP JSON Configuration 🤝 FastMCP
-sidebarTitle: MCP JSON
+sidebarTitle: MCP.json
 description: Generate standard MCP configuration files for any compatible client
 icon: brackets-curly
 tag: NEW

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/openai.mdx

@@ -3,7 +3,6 @@ title: OpenAI API 🤝 FastMCP
 sidebarTitle: OpenAI API
 description: Call FastMCP servers from the OpenAI API
 icon: message-code
-tag: NEW
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx"

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/integrations/permit.mdx

@@ -1,9 +1,8 @@
 ---
 title: Permit.io Authorization 🤝 FastMCP
-sidebarTitle: Permit.io Permissions
+sidebarTitle: Permit.io
 description: Add fine-grained authorization to your FastMCP servers with Permit.io
 icon: shield-check
-tag: NEW
 ---
 
 Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Permit.io][permit-github] authorization middleware**.

{fastmcp-2.11.0 → fastmcp-2.11.2}/docs/patterns/cli.mdx

@@ -18,15 +18,13 @@ fastmcp --help
 
 | Command | Purpose | Dependency Management |
 | ------- | ------- | --------------------- |
-| `run` | Run a FastMCP server directly | Default: Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess |
-| `dev` | Run a server with the MCP Inspector for testing | Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project |
-| `install` | Install a server in MCP client applications | Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable` |
-| `inspect` | Generate a JSON report about a FastMCP server | Uses your current environment; you are responsible for ensuring all dependencies are available |
+| `run` | Run a FastMCP server directly | **Supports:** Local files, factory functions, URLs, MCP configs. **Deps:** Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess |
+| `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files only. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project |
+| `install` | Install a server in MCP client applications | **Supports:** Local files only. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable` |
+| `inspect` | Generate a JSON report about a FastMCP server | **Supports:** Local files only. **Deps:** Uses your current environment; you are responsible for ensuring all dependencies are available |
 | `version` | Display version information | N/A |
 
-## Command Details
-
-### `run`
+## `fastmcp run`
 
 Run a FastMCP server directly or proxy a remote server.
 
@@ -38,7 +36,7 @@ fastmcp run server.py
 By default, this command runs the server directly in your current Python environment. You are responsible for ensuring all dependencies are available. When using `--python`, `--with`, `--project`, or `--with-requirements` options, it runs the server via `uv run` subprocess instead.
 </Tip>
 
-#### Options
+### Options
 
 | Option | Flag | Description |
 | ------ | ---- | ----------- |
@@ -54,106 +52,125 @@ By default, this command runs the server directly in your current Python environ
 | Requirements File | `--with-requirements` | Requirements file to install dependencies from |
 
 
-#### Server Specification
+### Entrypoints
 <VersionBadge version="2.3.5" />
 
-The server can be specified in four ways:
-1. `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
-2. `server.py:custom_name` - imports and uses the specified server object
-3. `http://server-url/path` or `https://server-url/path` - connects to a remote server and creates a proxy
-4. `mcp.json` - runs servers defined in a standard MCP configuration file
+The `fastmcp run` command supports the following entrypoints:
 
-<Tip>
-When using `fastmcp run` with a local file, it **ignores** the `if __name__ == "__main__"` block entirely. Instead, it finds your server object and calls its `run()` method directly with the transport options you specify. This means you can use `fastmcp run` to override the transport specified in your code.
-</Tip>
+1. **[Inferred server instance](#inferred-server-instance)**: `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **[Explicit server object](#explicit-server-object)**: `server.py:custom_name` - imports and uses the specified server object  
+3. **[Factory function](#factory-function)**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **[Remote server proxy](#remote-server-proxy)**: `https://example.com/mcp-server` - connects to a remote server and creates a **local proxy server**
+5. **MCP configuration file**: `mcp.json` - runs servers defined in a standard MCP configuration file
 
-For example, if your code contains:
+<Warning>
+Note: When using `fastmcp run` with a local file, it **completely ignores** the `if __name__ == "__main__"` block. This means:
+- Any setup code in `__main__` will NOT run
+- Server configuration in `__main__` is bypassed  
+- `fastmcp run` finds your server object/factory and runs it with its own transport settings
 
-```python
-# server.py
+If you need setup code to run, use the **factory pattern** instead.
+</Warning>
+
+#### Inferred Server Instance
+
+If you provide a path to a file, `fastmcp run` will load the file and look for a FastMCP server instance stored as a variable named `mcp`, `server`, or `app`. If no such object is found, it will raise an error.
+
+For example, if you have a file called `server.py` with the following content:
+
+```python server.py
 from fastmcp import FastMCP
 
 mcp = FastMCP("MyServer")
+```
 
-@mcp.tool
-def hello(name: str) -> str:
-    return f"Hello, {name}!"
+You can run it with:
 
-if __name__ == "__main__":
-    # This is ignored when using `fastmcp run`!
-    mcp.run(transport="stdio")
+```bash
+fastmcp run server.py
 ```
 
-You can run it with Streamable HTTP transport regardless of what's in the `__main__` block:
+#### Explicit Server Object
+
+If your server is stored as a variable with a custom name, or you want to be explicit about which server to run, you can use the following syntax to load a specific server object:
 
 ```bash
-fastmcp run server.py --transport http --port 8000
+fastmcp run server.py:custom_name
 ```
 
-**Examples**
+For example, if you have a file called `server.py` with the following content:
+
+```python
+from fastmcp import FastMCP
+
+my_server = FastMCP("CustomServer")
+
+@my_server.tool
+def hello() -> str:
+    return "Hello from custom server!"
+```
+
+You can run it with:
 
 ```bash
-# Run a local server with Streamable HTTP transport on a custom port
-fastmcp run server.py --transport http --port 8000
+fastmcp run server.py:custom_name
+```
 
-# Connect to a remote server and proxy as a stdio server
-fastmcp run https://example.com/mcp-server
+#### Factory Function
+<VersionBadge version="2.11.2" />
 
-# Connect to a remote server with specified log level
-fastmcp run https://example.com/mcp-server --log-level DEBUG
+Since `fastmcp run` ignores the `if __name__ == "__main__"` block, you can use a factory function to run setup code before your server starts. Factory functions are called without any arguments and must return a FastMCP server instance. Both sync and async factory functions are supported.
 
-# Run with a specific Python version
-fastmcp run server.py --python 3.11
+The syntax for using a factory function is the same as for an explicit server object: `fastmcp run server.py:factory_fn`. FastMCP will automatically detect that you have identified a function rather than a server Instance
 
-# Run with additional packages
-fastmcp run server.py --with pandas --with numpy
+For example, if you have a file called `server.py` with the following content:
 
-# Run within a specific project directory
-fastmcp run server.py --project /path/to/project
+```python
+from fastmcp import FastMCP
 
-# Run with dependencies from a requirements file
-fastmcp run server.py --with-requirements requirements.txt
+async def create_server() -> FastMCP:
+    mcp = FastMCP("MyServer")
+    
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+    
+    # Setup that runs with fastmcp run
+    tool = await mcp.get_tool("add")
+    tool.disable()
+    
+    return mcp
 ```
 
-#### Running MCP Configuration Files
+You can run it with:
 
-FastMCP can run servers defined in standard MCP configuration files (typically named `mcp.json`). When you run an mcp.json file, FastMCP creates a proxy server that runs all the servers referenced in the configuration.
-
-**Example mcp.json:**
-```json
-{
-    "mcpServers": {
-        "fetch": {
-            "command": "uvx",
-            "args": [
-                "mcp-server-fetch"
-            ]
-        },
-        "filesystem": {
-            "command": "npx",
-            "args": [
-                "-y",
-                "@modelcontextprotocol/server-filesystem",
-                "/Users/username/Documents"
-            ]
-        }
-    }
-}
+```bash
+fastmcp run server.py:create_server
 ```
 
-**Run the configuration:**
+#### Remote Server Proxy
+
+FastMCP run can also start a local proxy server that connects to a remote server. This is useful when you want to run a remote server locally for testing or development purposes, or to use with a client that doesn't support direct connections to remote servers.
+
+To start a local proxy, you can use the following syntax:
+
 ```bash
-# Run with default stdio transport
-fastmcp run mcp.json
+fastmcp run https://example.com/mcp
+```
+
+#### MCP Configuration
+
+FastMCP can also run servers defined in a standard MCP configuration file. This is useful when you want to run multiple servers from a single file, or when you want to use a client that doesn't support direct connections to remote servers.
 
-# Run with HTTP transport on custom port
-fastmcp run mcp.json --transport http --port 8080
+To run a MCP configuration file, you can use the following syntax:
 
-# Run with SSE transport
-fastmcp run mcp.json --transport sse
+```bash
+fastmcp run mcp.json
 ```
 
-### `dev`
+This will run all the servers defined in the file.
+
+## `fastmcp dev`
 
 Run a MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing.
 
@@ -182,7 +199,7 @@ This command does not support HTTP testing. To test a server over Streamable HTT
 2. Open the MCP Inspector separately and connect to your running server
 </Warning>
 
-#### Options
+### Options
 
 | Option | Flag | Description |
 | ------ | ---- | ----------- |
@@ -195,6 +212,18 @@ This command does not support HTTP testing. To test a server over Streamable HTT
 | Project Directory | `--project` | Run the command within the given project directory |
 | Requirements File | `--with-requirements` | Requirements file to install dependencies from |
 
+### Entrypoints
+
+The `dev` command supports local FastMCP server files only:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server object**: `server.py:custom_name` - imports and uses the specified server object  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+
+<Warning>
+The `dev` command **only supports local files** - no URLs, remote servers, or MCP configuration files.
+</Warning>
+
 **Examples**
 
 ```bash
@@ -211,7 +240,7 @@ fastmcp dev server.py --with-requirements requirements.txt
 fastmcp dev server.py --project /path/to/project
 ```
 
-### `install`
+## `fastmcp install`
 <VersionBadge version="2.10.3" />
 
 Install a MCP server in MCP client applications. FastMCP currently supports the following clients:
@@ -242,14 +271,7 @@ Note that for security reasons, MCP clients usually run every server in a comple
 **FastMCP `install` commands focus on local server files with STDIO transport.** For remote servers running with HTTP or SSE transport, use your client's native configuration - FastMCP's value is simplifying the complex local setup with dependencies and `uv` commands.
 </Tip>
 
-#### Server Specification
-
-The `install` command supports the same `file.py:object` notation as the `run` command:
-
-1. `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
-2. `server.py:custom_name` - imports and uses the specified server object
-
-#### Options
+### Options
 
 | Option | Flag | Description |
 | ------ | ---- | ----------- |
@@ -262,6 +284,22 @@ The `install` command supports the same `file.py:object` notation as the `run` c
 | Project Directory | `--project` | Run the command within the given project directory |
 | Requirements File | `--with-requirements` | Requirements file to install dependencies from |
 
+### Entrypoints
+
+The `install` command supports local FastMCP server files only:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server object**: `server.py:custom_name` - imports and uses the specified server object  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+
+<Note>
+Factory functions are particularly useful for install commands since they allow setup code to run that would otherwise be ignored when the MCP client runs your server.
+</Note>
+
+<Warning>
+The `install` command **only supports local files** - no URLs, remote servers, or MCP configuration files. For remote servers, use your MCP client's native configuration.
+</Warning>
+
 **Examples**
 
 ```bash
@@ -299,7 +337,7 @@ fastmcp install mcp-json server.py --name "My Server" --with pandas
 fastmcp install mcp-json server.py --copy
 ```
 
-#### MCP JSON Generation
+### MCP JSON Generation
 
 The `mcp-json` subcommand generates standard MCP JSON configuration that can be used with any MCP-compatible client. This is useful when:
 
@@ -339,7 +377,7 @@ To use this configuration with your MCP client, you'll typically need to add it
 | ------ | ---- | ----------- |
 | Copy to Clipboard | `--copy` | Copy configuration to clipboard instead of printing to stdout |
 
-### `inspect`
+## `fastmcp inspect`
 
 <VersionBadge version="2.9.0" />
 
@@ -349,7 +387,25 @@ Generate a detailed JSON report about a FastMCP server, including information ab
 fastmcp inspect server.py
 ```
 
-The command supports the same server specification format as `run` and `install`:
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Output File | `--output`, `-o` | Output file path for the JSON report (default: server-info.json) |
+
+### Entrypoints
+
+The `inspect` command supports local FastMCP server files only:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server object**: `server.py:custom_name` - imports and uses the specified server object  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+
+<Warning>
+The `inspect` command **only supports local files** - no URLs, remote servers, or MCP configuration files.
+</Warning>
+
+**Examples**
 
 ```bash
 # Auto-detect server object
@@ -362,7 +418,7 @@ fastmcp inspect server.py:my_server
 fastmcp inspect server.py --output analysis.json
 ```
 
-### `version`
+## `fastmcp version`
 
 Display version information about FastMCP and related components.
 
@@ -370,7 +426,7 @@ Display version information about FastMCP and related components.
 fastmcp version
 ```
 
-#### Options
+### Options
 
 | Option | Flag | Description |
 | ------ | ---- | ----------- |