fastmcp 2.13.0rc1__tar.gz → 2.13.0rc2__tar.gz

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/.github/workflows/marvin-dedupe-issues.yml

@@ -80,6 +80,7 @@ jobs:
           bot_name: "Marvin Context Protocol"
           prompt: ${{ steps.dedupe-prompt.outputs.PROMPT }}
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}
+          allowed_non_write_users: "*"
           claude_args: |
             --allowedTools Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh api:*),Bash(gh issue comment:*),Task
             --mcp-config /tmp/mcp-config/mcp-servers.json

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/.github/workflows/marvin-label-triage.yml

@@ -131,7 +131,7 @@ jobs:
           bot_name: "Marvin Context Protocol"
           prompt: ${{ steps.triage-prompt.outputs.PROMPT }}
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}
-          allowed_non_write_users: "*" # Required for issue triage workflow, if users without repo write access create issues
+          allowed_non_write_users: "*"
           claude_args: |
             --allowedTools Bash(gh label list),mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__get_pull_request_files
           settings: |

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.13.0rc1
+Version: 2.13.0rc2
 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.13.0rc1 → fastmcp-2.13.0rc2}/docs/changelog.mdx

@@ -4,6 +4,21 @@ icon: "list-check"
 rss: true
 ---
 
+<Update label="v2.12.5" description="2025-10-17">
+
+**[v2.12.5: Safety Pin](https://github.com/jlowin/fastmcp/releases/tag/v2.12.5)**
+
+FastMCP 2.12.5 is a point release that pins the MCP SDK version below 1.17, which introduced a change affecting FastMCP users with auth providers mounted as part of a larger application. This ensures the `.well-known` payload appears in the expected location when using FastMCP authentication providers with composite applications.
+
+## What's Changed
+
+### Fixes 🐞
+* Pin MCP SDK version below 1.17 by [@jlowin](https://github.com/jlowin) in [a1b2c3d](https://github.com/jlowin/fastmcp/commit/dab2b316ddc3883b7896a86da21cacb68da01e5c)
+
+**Full Changelog**: [v2.12.4...v2.12.5](https://github.com/jlowin/fastmcp/compare/v2.12.4...v2.12.5)
+
+</Update>
+
 <Update label="v2.12.4" description="2025-09-26">
 
 **[v2.12.4: OIDC What You Did There](https://github.com/jlowin/fastmcp/releases/tag/v2.12.4)**

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/clients/elicitation.mdx

@@ -3,7 +3,6 @@ title: User Elicitation
 sidebarTitle: Elicitation
 description: Handle server-initiated user input requests with structured schemas.
 icon: message-question
-tag: NEW
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx";

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/deployment/http.mdx

@@ -145,6 +145,59 @@ middleware = [
 http_app = mcp.http_app(middleware=middleware)
 ```
 
+### CORS for Browser-Based Clients
+
+<Tip>
+Most MCP clients, including those that you access through a browser like ChatGPT or Claude, don't need CORS configuration. Only enable CORS if you're working with an MCP client that connects directly from a browser, such as debugging tools or inspectors.
+</Tip>
+
+CORS (Cross-Origin Resource Sharing) is needed when JavaScript running in a web browser connects directly to your MCP server. This is different from using an LLM through a browser—in that case, the browser connects to the LLM service, and the LLM service connects to your MCP server (no CORS needed).
+
+Browser-based MCP clients that need CORS include:
+
+- **MCP Inspector** - Browser-based debugging tool for testing MCP servers
+- **Custom browser-based MCP clients** - If you're building a web app that directly connects to MCP servers
+
+For these scenarios, add CORS middleware with the specific headers required for MCP protocol:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+mcp = FastMCP("MyServer")
+
+# Configure CORS for browser-based clients
+middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow all origins; use specific origins for security
+        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_headers=[
+            "mcp-protocol-version",
+            "mcp-session-id",
+            "Authorization",
+            "Content-Type",
+        ],
+        expose_headers=["mcp-session-id"],
+    )
+]
+
+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)
+- **`expose_headers`**: Must include `mcp-session-id` so JavaScript can read the session ID from responses and send it in subsequent requests
+
+Without `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.
+
+<Warning>
+**Production Security**: Never use `allow_origins=["*"]` in production. Specify the exact origins of your browser-based clients. Using wildcards exposes your server to unauthorized access from any website.
+</Warning>
+
 ## Integration with Web Frameworks
 
 If you already have a web application running, you can add MCP capabilities by mounting a FastMCP server as a sub-application. This allows you to expose MCP tools alongside your existing API endpoints, sharing the same domain and infrastructure. The MCP server becomes just another route in your application, making it easy to manage and deploy.
@@ -280,6 +333,14 @@ OAuth specifications (RFC 8414 and RFC 9728) require discovery metadata to be ac
 Follow the configuration instructions below to set up mounting correctly.
 </Warning>
 
+<Warning>
+**CORS Middleware Conflicts:**
+
+If you're integrating FastMCP into an existing application with its own CORS middleware, be aware that layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+FastMCP and the MCP SDK already handle CORS for OAuth routes. If you need CORS on your own application routes, consider using the sub-app pattern: mount FastMCP and your routes as separate apps, each with their own middleware, rather than adding application-wide CORS middleware.
+</Warning>
+
 ### Route Types
 
 OAuth-protected MCP servers expose two categories of routes:

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/development/upgrade-guide.mdx

@@ -3,6 +3,7 @@ title: Upgrade Guide
 sidebarTitle: Upgrade Guide
 description: Migration instructions for upgrading between FastMCP versions
 icon: up
+tag: NEW
 ---
 
 This guide provides migration instructions for breaking changes and major updates when upgrading between FastMCP versions.

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/docs.json

@@ -19,11 +19,12 @@
     "light": "#4cc9f0",
     "primary": "#2d00f7"
   },
+  "fonts": {
+    "heading": { "family": "Google Sans" },
+    "body": { "family": "BlinkMacSystemFont" }
+  },
   "contextual": {
-    "options": [
-      "copy",
-      "view"
-    ]
+    "options": ["copy", "view"]
   },
   "description": "The fast, Pythonic way to build MCP servers and clients.",
   "errors": {
@@ -107,15 +108,16 @@
                 "group": "Advanced Features",
                 "icon": "stars",
                 "pages": [
-                  "servers/icons",
-                  "servers/context",
-                  "servers/proxy",
                   "servers/composition",
+                  "servers/context",
                   "servers/elicitation",
+                  "servers/icons",
                   "servers/logging",
+                  "servers/middleware",
                   "servers/progress",
+                  "servers/proxy",
                   "servers/sampling",
-                  "servers/middleware"
+                  "servers/storage-backends"
                 ]
               },
               {
@@ -148,10 +150,7 @@
               {
                 "group": "Essentials",
                 "icon": "cube",
-                "pages": [
-                  "clients/client",
-                  "clients/transports"
-                ]
+                "pages": ["clients/client", "clients/transports"]
               },
               {
                 "group": "Core Operations",
@@ -177,10 +176,7 @@
               {
                 "group": "Authentication",
                 "icon": "user-shield",
-                "pages": [
-                  "clients/auth/oauth",
-                  "clients/auth/bearer"
-                ]
+                "pages": ["clients/auth/oauth", "clients/auth/bearer"]
               }
             ]
           },
@@ -234,10 +230,7 @@
               {
                 "group": "API Integration",
                 "icon": "globe",
-                "pages": [
-                  "integrations/fastapi",
-                  "integrations/openapi"
-                ]
+                "pages": ["integrations/fastapi", "integrations/openapi"]
               }
             ]
           },
@@ -472,5 +465,13 @@
   "thumbnails": {
     "appearance": "light",
     "background": "/assets/brand/thumbnail-background.png"
+  },
+  "styling": {
+    "codeblocks": {
+      "theme": {
+        "light": "snazzy-light",
+        "dark": "dark-plus"
+      }
+    }
   }
 }

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/getting-started/welcome.mdx

@@ -3,7 +3,6 @@ title: "Welcome to FastMCP 2.0!"
 sidebarTitle: "Welcome!"
 description: The fast, Pythonic way to build MCP servers and clients.
 icon: hand-wave
-mode: wide
 ---
 <img 
   src="/assets/brand/f-watercolor-waves.png" 

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/integrations/aws-cognito.mdx

@@ -86,21 +86,19 @@ Set up AWS Cognito user pool with an app client to get the credentials needed fo
     </Tip>
 </Step>
 
-<Step title="Pick Up AWS Cognito Domain">
-    Navigate to **"Branding" → "Domain"** in the side navigation to find or configure Your AWS Cognito domain:
+<Step title="Configure Resource Server">
+    AWS Cognito requires a resource server entry to support OAuth with protected resources. Without this, token exchange will fail with an `invalid_grant` error.
 
-    **Option 1: Use Auto-Generated Domain**
-    - If AWS has already created a domain automatically, note the **domain prefix** (the part before `.auth.region.amazoncognito.com`)
-    - This prefix is what you'll use in your FastMCP configuration
+    Navigate to **"Branding" → "Domain"** in the side navigation, then:
 
-    **Option 2: Create a Custom Domain Prefix**
-    - If no domain exists or you want a better name, delete the existing domain and create a new one using the **"Actions"** menu
-    - Under **"Domain"** → **"Cognito domain"** in the **"Create Cognito domain"** dialog, enter a meaningful prefix (e.g., `my-app`) that is available in the AWS region you are in
-    - Just note the **domain prefix** you entered (e.g., `my-fastmcp-app`) - this is what you'll use in your FastMCP configuration
+    1. Click **"Create resource server"**
+    2. **Resource server name**: Enter a descriptive name (e.g., `My MCP Server`)
+    3. **Resource server identifier**: Enter your MCP endpoint URL exactly as it will be accessed (e.g., `http://localhost:8000/mcp` for development, or `https://your-server.com/mcp` for production)
+    4. Click **"Create resource server"**
 
-    <Info>
-    The FastMCP AWS Cognito provider automatically constructs the full domain from your prefix and region, simplifying configuration.
-    </Info>
+    <Warning>
+    The resource server identifier must exactly match your `base_url + mcp_path`. For the default configuration with `base_url="http://localhost:8000"` and `path="/mcp"`, use `http://localhost:8000/mcp`.
+    </Warning>
 </Step>
 
 <Step title="Save Your Credentials">
@@ -109,7 +107,6 @@ Set up AWS Cognito user pool with an app client to get the credentials needed fo
     - **User Pool ID**: Format like `eu-central-1_XXXXXXXXX`
     - **Client ID**: Your application's client identifier
     - **Client Secret**: Generated client secret (keep secure)
-    - **Domain Prefix**: The prefix of Your AWS Cognito domain
     - **AWS Region**: Where Your AWS Cognito user pool is located
 
     <Tip>

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/integrations/fastapi.mdx

@@ -407,6 +407,12 @@ app.mount("/mcp", mcp.http_app())  # Session manager won't initialize
 
 If you're mounting an authenticated MCP server under a path prefix, see [Mounting Authenticated Servers](/deployment/http#mounting-authenticated-servers) for important OAuth routing considerations.
 
+### CORS Middleware
+
+If your FastAPI app uses `CORSMiddleware` and you're mounting an OAuth-protected FastMCP server, avoid adding application-wide CORS middleware. FastMCP and the MCP SDK already handle CORS for OAuth routes, and layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+If you need CORS on your own FastAPI routes, use the sub-app pattern: mount your API and FastMCP as separate apps, each with their own middleware, rather than adding top-level `CORSMiddleware` to the combined application.
+
 ### Combining Lifespans
 
 If your FastAPI app already has a lifespan (for database connections, startup tasks, etc.), you can't simply replace it with the MCP lifespan. Instead, you need to create a new lifespan function that manages both contexts. This ensures that both your app's initialization logic and the MCP server's session manager run properly:

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/python-sdk/fastmcp-client-auth-oauth.mdx

@@ -7,7 +7,7 @@ sidebarTitle: oauth
 
 ## Functions
 
-### `check_if_auth_required` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `check_if_auth_required` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 check_if_auth_required(mcp_url: str, httpx_kwargs: dict[str, Any] | None = None) -> bool
@@ -22,47 +22,47 @@ Check if the MCP endpoint requires authentication by making a test request.
 
 ## Classes
 
-### `ClientNotFoundError` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `ClientNotFoundError` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 
 Raised when OAuth client credentials are not found on the server.
 
 
-### `TokenStorageAdapter` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `TokenStorageAdapter` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 **Methods:**
 
-#### `clear` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `clear` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 clear(self) -> None
 ```
 
-#### `get_tokens` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_tokens` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 get_tokens(self) -> OAuthToken | None
 ```
 
-#### `set_tokens` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_tokens` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 set_tokens(self, tokens: OAuthToken) -> None
 ```
 
-#### `get_client_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `get_client_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 get_client_info(self) -> OAuthClientInformationFull | None
 ```
 
-#### `set_client_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_client_info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 set_client_info(self, client_info: OAuthClientInformationFull) -> None
 ```
 
-### `OAuth` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `OAuth` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 
 OAuth client provider for MCP servers with browser-based authentication.
@@ -73,7 +73,7 @@ a browser for user authorization and running a local callback server.
 
 **Methods:**
 
-#### `redirect_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `redirect_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 redirect_handler(self, authorization_url: str) -> None
@@ -82,7 +82,7 @@ redirect_handler(self, authorization_url: str) -> None
 Open browser for authorization, with pre-flight check for invalid client.
 
 
-#### `callback_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `callback_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 callback_handler(self) -> tuple[str, str | None]
@@ -91,7 +91,7 @@ callback_handler(self) -> tuple[str, str | None]
 Handle OAuth callback and return (auth_code, state).
 
 
-#### `async_auth_flow` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `async_auth_flow` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L284" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]

{fastmcp-2.13.0rc1 → fastmcp-2.13.0rc2}/docs/python-sdk/fastmcp-client-oauth_callback.mdx

@@ -25,10 +25,10 @@ create_callback_html(message: str, is_success: bool = True, title: str = 'FastMC
 Create a styled HTML response for OAuth callbacks.
 
 
-### `create_oauth_callback_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `create_oauth_callback_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
-create_oauth_callback_server(port: int, callback_path: str = '/callback', server_url: str | None = None, response_future: asyncio.Future | None = None) -> Server
+create_oauth_callback_server(port: int, callback_path: str = '/callback', server_url: str | None = None, result_container: OAuthCallbackResult | None = None, result_ready: anyio.Event | None = None) -> Server
 ```
 
 
@@ -38,7 +38,8 @@ Create an OAuth callback server.
 - `port`: The port to run the server on
 - `callback_path`: The path to listen for OAuth redirects on
 - `server_url`: Optional server URL to display in success messages
-- `response_future`: Optional future to resolve when OAuth callback is received
+- `result_container`: Optional container to store callback results
+- `result_ready`: Optional event to signal when callback is received
 
 **Returns:**
 - Configured uvicorn Server instance (not yet running)
@@ -61,3 +62,9 @@ from_dict(cls, data: dict[str, str]) -> CallbackResponse
 ```python
 to_dict(self) -> dict[str, str]
 ```
+
+### `OAuthCallbackResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Container for OAuth callback results, used with anyio.Event for async coordination.
+