π The fast, Pythonic way to build MCP servers and clients.
AuthKit: auto-bind token audience to resource URL (RFC 8707) (#3905)
Jeremiah Lowin82f310fe61db
diff --git a/docs/integrations/authkit.mdx b/docs/integrations/authkit.mdxindex e99f78351..c77175201 100644--- a/docs/integrations/authkit.mdx+++ b/docs/integrations/authkit.mdx@@ -9,29 +9,32 @@ import { VersionBadge } from "/snippets/version-badge.mdx"<VersionBadge version="2.11.0" />-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.--<Warning>-AuthKit does not currently support [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) resource indicators, so FastMCP cannot validate that tokens were issued for the specific resource server. If you need resource-specific audience validation, consider using [WorkOSProvider](/integrations/workos) (OAuth proxy pattern) instead.-</Warning>+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 with [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) resource indicators: AuthKit issues tokens whose `aud` claim is bound to your server's resource URL, and FastMCP validates that claim automatically.## Configuration+### PrerequisitesBefore you begin, you will need: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`).+3. Your FastMCP server's URL (can be localhost for development, e.g., `http://127.0.0.1:8000`).-### Step 1: AuthKit Configuration+### Step 1: WorkOS Dashboard-In your WorkOS Dashboard, enable AuthKit and configure the following settings:+In the WorkOS Dashboard, go to **Connect β Configuration** and configure:<Steps>-<Step title="Enable Dynamic Client Registration">- Go to **Applications β Configuration** and enable **Dynamic Client Registration**. This allows MCP clients register with your application automatically.+<Step title="MCP Auth">+ Enable **Dynamic Client Registration** (DCR) so MCP clients can register themselves. Alternatively, enable **Client ID Metadata Document** (CIMD) if your clients support it.+</Step>- +<Step title="MCP resource indicators">+ Add your FastMCP server's resource URL (e.g., `http://127.0.0.1:8000/mcp`) as a valid resource indicator.++ This must exactly match what FastMCP advertises in its protected resource metadata. Start your server first and it will log the correct URL on startup β copy that value.++ Without this step, AuthKit falls back to a default environment-scoped audience and audience validation will fail with a 401.</Step><Step title="Note Your AuthKit Domain">@@ -47,16 +50,18 @@ Create your FastMCP server file and use the `AuthKitProvider` to handle all thefrom fastmcp import FastMCPfrom fastmcp.server.auth.providers.workos import AuthKitProvider-# The AuthKitProvider automatically discovers WorkOS endpoints-# and configures JWT token validation+# AuthKitProvider automatically discovers WorkOS endpoints, configures JWT+# validation, and binds the token audience to this server's resource URL.auth_provider = AuthKitProvider(authkit_domain="https://your-project-12345.authkit.app",- base_url="http://localhost:8000" # Use your actual server URL+ base_url="http://127.0.0.1:8000", # Use your actual server URL)mcp = FastMCP(name="AuthKit Secured App", auth=auth_provider)```+When the server starts, it logs the resource URL it is validating against. Paste that URL into your Dashboard's **MCP resource indicators** list.+## TestingTo test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the `authkit_domain` and `base_url` with your actual values!), you can run the following command:@@ -75,7 +80,7 @@ import asyncioauth = OAuth(additional_client_metadata={"token_endpoint_auth_method": "none"})async def main():- async with Client("http://localhost:8000/mcp", auth=auth) as client:+ async with Client("http://127.0.0.1:8000/mcp", auth=auth) as client:assert await client.ping()if __name__ == "__main__":@@ -94,7 +99,7 @@ from fastmcp.server.auth.providers.workos import AuthKitProvider# Load configuration from environment variablesauth = AuthKitProvider(authkit_domain=os.environ.get("AUTHKIT_DOMAIN"),- base_url=os.environ.get("BASE_URL", "https://your-server.com")+ base_url=os.environ.get("BASE_URL", "https://your-server.com"),)mcp = FastMCP(name="AuthKit Secured App", auth=auth)diff --git a/examples/auth/authkit/README.md b/examples/auth/authkit/README.mdnew file mode 100644index 000000000..8c4b8a6aa--- /dev/null+++ b/examples/auth/authkit/README.md@@ -0,0 +1,36 @@+# AuthKit Example++Protects a FastMCP server with WorkOS AuthKit. The server binds the JWT+`aud` claim to its own resource URL automatically β you just paste that same+URL into the WorkOS Dashboard as a resource indicator.++## WorkOS Dashboard setup++In the WorkOS Dashboard for your project, go to **Connect β Configuration** and:++1. Under **MCP Auth**, enable **Dynamic Client Registration** (or **Client ID+ Metadata Document** if your MCP client supports it).+2. Under **MCP resource indicators**, add `http://127.0.0.1:8000/mcp` as a+ valid resource indicator.++## Running++1. Set your AuthKit domain:++ ```bash+ export AUTHKIT_DOMAIN="https://your-app.authkit.app"+ ```++2. Start the server. It logs the resource URL it's validating against β+ that's the URL that must match your dashboard resource indicator:++ ```bash+ python server.py+ ```++3. In another terminal, run the client. Your browser will open for AuthKit+ authentication:++ ```bash+ python client.py+ ```diff --git a/examples/auth/authkit_dcr/client.py b/examples/auth/authkit/client.pysimilarity index 100%rename from examples/auth/authkit_dcr/client.pyrename to examples/auth/authkit/client.pydiff --git a/examples/auth/authkit_dcr/server.py b/examples/auth/authkit/server.pysimilarity index 50%rename from examples/auth/authkit_dcr/server.pyrename to examples/auth/authkit/server.pyindex 8974376d2..7611ccddf 100644--- a/examples/auth/authkit_dcr/server.py+++ b/examples/auth/authkit/server.py@@ -1,9 +1,11 @@-"""AuthKit DCR server example for FastMCP.+"""AuthKit server example for FastMCP.-This example demonstrates how to protect a FastMCP server with AuthKit DCR.+Demonstrates an MCP server secured by WorkOS AuthKit. FastMCP binds the JWT+audience to this server's resource URL automatically; you configure the same+URL as an MCP resource indicator in the WorkOS Dashboard.Required environment variables:-- FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN: Your AuthKit domain (e.g., "https://your-app.authkit.app")+- AUTHKIT_DOMAIN: Your AuthKit domain (e.g., "https://your-app.authkit.app")To run:python server.py@@ -16,10 +18,10 @@ from fastmcp.server.auth.providers.workos import AuthKitProviderauth = AuthKitProvider(authkit_domain=os.getenv("AUTHKIT_DOMAIN") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",)-mcp = FastMCP("AuthKit DCR Example Server", auth=auth)+mcp = FastMCP("AuthKit Example Server", auth=auth)@mcp.tooldiff --git a/examples/auth/authkit_dcr/README.md b/examples/auth/authkit_dcr/README.mddeleted file mode 100644index 808246199..000000000--- a/examples/auth/authkit_dcr/README.md+++ /dev/null@@ -1,25 +0,0 @@-# AuthKit DCR Example--Demonstrates FastMCP server protection with AuthKit Dynamic Client Registration.--## Setup--1. Set your AuthKit domain:-- ```bash- export AUTHKIT_DOMAIN="https://your-app.authkit.app"- ```--2. Run the server:-- ```bash- python server.py- ```--3. In another terminal, run the client:-- ```bash- python client.py- ```--The client will open your browser for AuthKit authentication.diff --git a/examples/auth/aws_oauth/README.md b/examples/auth/aws_oauth/README.mdindex 9abff838c..c4e25b1f8 100644--- a/examples/auth/aws_oauth/README.md+++ b/examples/auth/aws_oauth/README.md@@ -10,7 +10,7 @@ Demonstrates FastMCP server protection with AWS Cognito OAuth.- Create an App Client in your User Pool- Configure the App Client settings:- Enable "Authorization code grant" flow- - Add Callback URL: `http://localhost:8000/auth/callback`+ - Add Callback URL: `http://127.0.0.1:8000/auth/callback`- Configure OAuth scopes (at minimum: `openid`)- Note your User Pool ID, App Client ID, Client Secret, and Cognito Domain Prefixdiff --git a/examples/auth/aws_oauth/client.py b/examples/auth/aws_oauth/client.pyindex 4043e6d4f..afcf54fd1 100644--- a/examples/auth/aws_oauth/client.py+++ b/examples/auth/aws_oauth/client.py@@ -10,7 +10,7 @@ import asynciofrom fastmcp.client import Client-SERVER_URL = "http://localhost:8000/mcp"+SERVER_URL = "http://127.0.0.1:8000/mcp"async def main():diff --git a/examples/auth/aws_oauth/server.py b/examples/auth/aws_oauth/server.pyindex dfe596a83..261164391 100644--- a/examples/auth/aws_oauth/server.py+++ b/examples/auth/aws_oauth/server.py@@ -31,7 +31,7 @@ auth = AWSCognitoProvider(or "eu-central-1",client_id=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID") or "",client_secret=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/custom/callback")diff --git a/examples/auth/azure_oauth/README.md b/examples/auth/azure_oauth/README.mdindex ba0757ca7..98d9ae756 100644--- a/examples/auth/azure_oauth/README.md+++ b/examples/auth/azure_oauth/README.md@@ -10,7 +10,7 @@ This example demonstrates how to use the Azure OAuth provider with FastMCP serve2. Click "New registration" and configure:- Name: Your app name- Supported account types: Choose based on your needs- - Redirect URI: `http://localhost:8000/auth/callback` (Web platform)+ - Redirect URI: `http://127.0.0.1:8000/auth/callback` (Web platform)3. After creation, go to "Certificates & secrets" β "New client secret"4. Note these values from the Overview page:- Application (client) IDdiff --git a/examples/auth/azure_oauth/server.py b/examples/auth/azure_oauth/server.pyindex d214389aa..e0c9e799e 100644--- a/examples/auth/azure_oauth/server.py+++ b/examples/auth/azure_oauth/server.py@@ -24,7 +24,7 @@ auth = AzureProvider(client_secret=os.getenv("FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET") or "",tenant_id=os.getenv("FASTMCP_SERVER_AUTH_AZURE_TENANT_ID")or "", # Required for single-tenant apps - get from Azure Portal- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",required_scopes=["read"],# required_scopes is automatically loaded from FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES# At least one scope is required - use unprefixed scope names from your Azure App (e.g., ["read", "write"])diff --git a/examples/auth/clerk_oauth/README.md b/examples/auth/clerk_oauth/README.mdindex 84d2b44b1..9a79ff566 100644--- a/examples/auth/clerk_oauth/README.md+++ b/examples/auth/clerk_oauth/README.md@@ -9,7 +9,7 @@ Demonstrates FastMCP server protection with Clerk OAuth.- Create or select an application- Go to Developers > OAuth Applications- Create an OAuth application- - Add Authorized redirect URI: `http://localhost:8000/auth/callback`+ - Add Authorized redirect URI: `http://127.0.0.1:8000/auth/callback`- Copy the Client ID and Client Secret- Note your instance domain (e.g., `saving-primate-16.clerk.accounts.dev`)diff --git a/examples/auth/clerk_oauth/server.py b/examples/auth/clerk_oauth/server.pyindex 74b1e4687..e7d080734 100644--- a/examples/auth/clerk_oauth/server.py+++ b/examples/auth/clerk_oauth/server.py@@ -21,7 +21,7 @@ auth = ClerkProvider(domain=os.getenv("FASTMCP_SERVER_AUTH_CLERK_DOMAIN") or "",client_id=os.getenv("FASTMCP_SERVER_AUTH_CLERK_CLIENT_ID") or "",client_secret=os.getenv("FASTMCP_SERVER_AUTH_CLERK_CLIENT_SECRET") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/auth/callback", # Default path - change if using a different callback URL# Optional: specify required scopes (defaults to ["openid", "email", "profile"])# required_scopes=["openid", "email", "profile", "public_metadata"],diff --git a/examples/auth/discord_oauth/README.md b/examples/auth/discord_oauth/README.mdindex 74217f833..e757ad84b 100644--- a/examples/auth/discord_oauth/README.md+++ b/examples/auth/discord_oauth/README.md@@ -8,7 +8,7 @@ Demonstrates FastMCP server protection with Discord OAuth.- Go to https://discord.com/developers/applications- Click "New Application" and give it a name- Go to OAuth2 in the left sidebar- - Add a Redirect URL: `http://localhost:8000/auth/callback`+ - Add a Redirect URL: `http://127.0.0.1:8000/auth/callback`- Copy the Client ID and Client Secret2. Set environment variables:diff --git a/examples/auth/discord_oauth/server.py b/examples/auth/discord_oauth/server.pyindex 424c97bdb..1e109b76a 100644--- a/examples/auth/discord_oauth/server.py+++ b/examples/auth/discord_oauth/server.py@@ -18,7 +18,7 @@ from fastmcp.server.auth.providers.discord import DiscordProviderauth = DiscordProvider(client_id=os.getenv("FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID") or "",client_secret=os.getenv("FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/auth/callback", # Default path - change if using a different callback URL)diff --git a/examples/auth/github_oauth/README.md b/examples/auth/github_oauth/README.mdindex 557ba7774..dcd5c2205 100644--- a/examples/auth/github_oauth/README.md+++ b/examples/auth/github_oauth/README.md@@ -6,7 +6,7 @@ Demonstrates FastMCP server protection with GitHub OAuth.1. Create a GitHub OAuth App:- Go to GitHub Settings > Developer settings > OAuth Apps- - Set Authorization callback URL to: `http://localhost:8000/auth/callback`+ - Set Authorization callback URL to: `http://127.0.0.1:8000/auth/callback`- Copy the Client ID and Client Secret2. Set environment variables:diff --git a/examples/auth/github_oauth/client.py b/examples/auth/github_oauth/client.pyindex 7158583bc..8722a547c 100644--- a/examples/auth/github_oauth/client.py+++ b/examples/auth/github_oauth/client.py@@ -10,7 +10,7 @@ import asynciofrom fastmcp.client import Client, OAuth-SERVER_URL = "http://localhost:8000/mcp"+SERVER_URL = "http://127.0.0.1:8000/mcp"async def main():diff --git a/examples/auth/github_oauth/server.py b/examples/auth/github_oauth/server.pyindex 1f88c6977..e93d6f01a 100644--- a/examples/auth/github_oauth/server.py+++ b/examples/auth/github_oauth/server.py@@ -18,7 +18,7 @@ from fastmcp.server.auth.providers.github import GitHubProviderauth = GitHubProvider(client_id=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID") or "",client_secret=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/auth/callback", # Default path - change if using a different callback URL)diff --git a/examples/auth/google_oauth/README.md b/examples/auth/google_oauth/README.mdindex 869718344..82bcd8696 100644--- a/examples/auth/google_oauth/README.md+++ b/examples/auth/google_oauth/README.md@@ -9,7 +9,7 @@ Demonstrates FastMCP server protection with Google OAuth.- Create or select a project- Go to APIs & Services > Credentials- Create OAuth 2.0 Client ID (Web application)- - Add Authorized redirect URI: `http://localhost:8000/auth/callback`+ - Add Authorized redirect URI: `http://127.0.0.1:8000/auth/callback`- Copy the Client ID and Client Secret2. Set environment variables:diff --git a/examples/auth/google_oauth/server.py b/examples/auth/google_oauth/server.pyindex 2a5b1c7df..2043ed6c3 100644--- a/examples/auth/google_oauth/server.py+++ b/examples/auth/google_oauth/server.py@@ -18,7 +18,7 @@ from fastmcp.server.auth.providers.google import GoogleProviderauth = GoogleProvider(client_id=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID") or "",client_secret=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET") or "",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/auth/callback", # Default path - change if using a different callback URL# Optional: specify required scopes# required_scopes=["openid", "https://www.googleapis.com/auth/userinfo.email"],diff --git a/examples/auth/keycloak_oauth/README.md b/examples/auth/keycloak_oauth/README.mdindex 68bdfeda6..ba6b95bf4 100644--- a/examples/auth/keycloak_oauth/README.md+++ b/examples/auth/keycloak_oauth/README.md@@ -6,7 +6,7 @@ Demonstrates FastMCP server protection with Keycloak OAuth.## Setup-1. Configure a Keycloak realm with Dynamic Client Registration enabled and a trusted host policy for your server URL (e.g. `http://localhost:8000/*`).+1. Configure a Keycloak realm with Dynamic Client Registration enabled and a trusted host policy for your server URL (e.g. `http://127.0.0.1:8000/*`).2. Set environment variables:diff --git a/examples/auth/keycloak_oauth/client.py b/examples/auth/keycloak_oauth/client.pyindex e180f1c56..4992abbab 100644--- a/examples/auth/keycloak_oauth/client.py+++ b/examples/auth/keycloak_oauth/client.py@@ -8,7 +8,7 @@ import asynciofrom fastmcp import Client-SERVER_URL = "http://localhost:8000/mcp"+SERVER_URL = "http://127.0.0.1:8000/mcp"async def main():diff --git a/examples/auth/keycloak_oauth/server.py b/examples/auth/keycloak_oauth/server.pyindex f236bdcd3..7b4653103 100644--- a/examples/auth/keycloak_oauth/server.py+++ b/examples/auth/keycloak_oauth/server.py@@ -16,8 +16,8 @@ from fastmcp.server.dependencies import get_access_tokenauth = KeycloakAuthProvider(realm_url=os.getenv("KEYCLOAK_REALM_URL") or "http://localhost:8080/realms/fastmcp",- base_url="http://localhost:8000",- # audience="http://localhost:8000", # Recommended for production+ base_url="http://127.0.0.1:8000",+ # audience="http://127.0.0.1:8000", # Recommended for production)mcp = FastMCP("Keycloak Example Server", auth=auth)diff --git a/examples/auth/mounted/README.md b/examples/auth/mounted/README.mdindex 5810dab4c..2bf213094 100644--- a/examples/auth/mounted/README.md+++ b/examples/auth/mounted/README.md@@ -4,12 +4,12 @@ This example demonstrates mounting multiple OAuth-protected MCP servers in a sin## URL Structure-- **GitHub MCP**: `http://localhost:8000/api/mcp/github/mcp`-- **Google MCP**: `http://localhost:8000/api/mcp/google/mcp`+- **GitHub MCP**: `http://127.0.0.1:8000/api/mcp/github/mcp`+- **Google MCP**: `http://127.0.0.1:8000/api/mcp/google/mcp`Discovery endpoints (RFC 8414 path-aware):-- **GitHub**: `http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/github`-- **Google**: `http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/google`+- **GitHub**: `http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/github`+- **Google**: `http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/google`## Setup@@ -23,8 +23,8 @@ export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="your-google-client-secret"```Configure redirect URIs in each provider's developer console (note the `/api/mcp/{provider}` prefix since the servers are mounted):-- GitHub: `http://localhost:8000/api/mcp/github/auth/callback/github`-- Google: `http://localhost:8000/api/mcp/google/auth/callback/google`+- GitHub: `http://127.0.0.1:8000/api/mcp/github/auth/callback/github`+- Google: `http://127.0.0.1:8000/api/mcp/google/auth/callback/google`## Runningdiff --git a/examples/auth/mounted/server.py b/examples/auth/mounted/server.pyindex 24aefdd59..c5b3af593 100644--- a/examples/auth/mounted/server.py+++ b/examples/auth/mounted/server.py@@ -5,10 +5,10 @@ application, each with its own provider. It showcases RFC 8414 path-aware discovwhere each server has its own authorization server metadata endpoint.URL structure:-- GitHub MCP: http://localhost:8000/api/mcp/github/mcp-- Google MCP: http://localhost:8000/api/mcp/google/mcp-- GitHub discovery: http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/github-- Google discovery: http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/google+- GitHub MCP: http://127.0.0.1:8000/api/mcp/github/mcp+- Google MCP: http://127.0.0.1:8000/api/mcp/google/mcp+- GitHub discovery: http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/github+- Google discovery: http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/googleRequired environment variables:- FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID: Your GitHub OAuth app client ID@@ -31,7 +31,7 @@ from fastmcp.server.auth.providers.github import GitHubProviderfrom fastmcp.server.auth.providers.google import GoogleProvider# Configuration-ROOT_URL = "http://localhost:8000"+ROOT_URL = "http://127.0.0.1:8000"API_PREFIX = "/api/mcp"# --- GitHub OAuth Server ---diff --git a/examples/auth/propelauth_oauth/README.md b/examples/auth/propelauth_oauth/README.mdindex 575ea7314..aa5b10ecf 100644--- a/examples/auth/propelauth_oauth/README.md+++ b/examples/auth/propelauth_oauth/README.md@@ -36,7 +36,7 @@ Create a `.env` file:PROPELAUTH_AUTH_URL=https://auth.yourdomain.comPROPELAUTH_INTROSPECTION_CLIENT_ID=your-client-idPROPELAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret-BASE_URL=http://localhost:8000/+BASE_URL=http://127.0.0.1:8000/# Optional: additional scopes tokens must include (comma-separated)# PROPELAUTH_REQUIRED_SCOPES=read:user_data```@@ -50,7 +50,7 @@ Start the server:uv run python server.py```-The server will start on `http://localhost:8000/mcp` with PropelAuth OAuth authentication enabled.+The server will start on `http://127.0.0.1:8000/mcp` with PropelAuth OAuth authentication enabled.Test with client:diff --git a/examples/auth/propelauth_oauth/server.py b/examples/auth/propelauth_oauth/server.pyindex 8401882aa..ab1661d22 100644--- a/examples/auth/propelauth_oauth/server.py+++ b/examples/auth/propelauth_oauth/server.py@@ -9,7 +9,7 @@ Required environment variables:Optional:- PROPELAUTH_REQUIRED_SCOPES: Comma-separated scopes tokens must include-- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://localhost:8000/`)+- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://127.0.0.1:8000/`)To run:python server.py@@ -29,7 +29,7 @@ auth = PropelAuthProvider(auth_url=os.environ["PROPELAUTH_AUTH_URL"],introspection_client_id=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_ID"],introspection_client_secret=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_SECRET"],- base_url=os.getenv("BASE_URL", "http://localhost:8000/"),+ base_url=os.getenv("BASE_URL", "http://127.0.0.1:8000/"),)mcp = FastMCP("PropelAuth OAuth Example Server", auth=auth)diff --git a/examples/auth/scalekit_oauth/README.md b/examples/auth/scalekit_oauth/README.mdindex c241d76f7..d16b81c37 100644--- a/examples/auth/scalekit_oauth/README.md+++ b/examples/auth/scalekit_oauth/README.md@@ -24,7 +24,7 @@ Create a `.env` file:# Required Scalekit credentialsSCALEKIT_ENVIRONMENT_URL=<YOUR_APP_ENVIRONMENT_URL>SCALEKIT_RESOURCE_ID=<YOUR_APP_RESOURCE_ID> # res_926EXAMPLE5878-BASE_URL=http://localhost:8000/+BASE_URL=http://127.0.0.1:8000/# Optional: additional scopes tokens must include (comma-separated)# SCALEKIT_REQUIRED_SCOPES=read,write```@@ -38,7 +38,7 @@ Start the server:uv run python server.py```-The server will start on `http://localhost:8000/mcp` with Scalekit OAuth authentication enabled.+The server will start on `http://127.0.0.1:8000/mcp` with Scalekit OAuth authentication enabled.Test with client:diff --git a/examples/auth/scalekit_oauth/server.py b/examples/auth/scalekit_oauth/server.pyindex 68cef23b5..09d4f5959 100644--- a/examples/auth/scalekit_oauth/server.py+++ b/examples/auth/scalekit_oauth/server.py@@ -8,7 +8,7 @@ Required environment variables:Optional:- SCALEKIT_REQUIRED_SCOPES: Comma-separated scopes tokens must include-- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://localhost:8000/`)+- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://127.0.0.1:8000/`)To run:python server.py@@ -30,7 +30,7 @@ auth = ScalekitProvider(environment_url=os.getenv("SCALEKIT_ENVIRONMENT_URL")or "https://your-env.scalekit.com",resource_id=os.getenv("SCALEKIT_RESOURCE_ID") or "",- base_url=os.getenv("BASE_URL", "http://localhost:8000/"),+ base_url=os.getenv("BASE_URL", "http://127.0.0.1:8000/"),required_scopes=required_scopes,)diff --git a/examples/auth/workos_oauth/server.py b/examples/auth/workos_oauth/server.pyindex 08c1db62b..4dba970a8 100644--- a/examples/auth/workos_oauth/server.py+++ b/examples/auth/workos_oauth/server.py@@ -20,7 +20,7 @@ auth = WorkOSProvider(client_id=os.getenv("WORKOS_CLIENT_ID") or "",client_secret=os.getenv("WORKOS_CLIENT_SECRET") or "",authkit_domain=os.getenv("WORKOS_AUTHKIT_DOMAIN") or "https://your-app.authkit.app",- base_url="http://localhost:8000",+ base_url="http://127.0.0.1:8000",# redirect_path="/auth/callback", # Default path - change if using a different callback URL)diff --git a/src/fastmcp/server/auth/auth.py b/src/fastmcp/server/auth/auth.pyindex c060c0fa6..852f440a4 100644--- a/src/fastmcp/server/auth/auth.py+++ b/src/fastmcp/server/auth/auth.py@@ -477,6 +477,12 @@ class RemoteAuthProvider(AuthProvider):Creates protected resource metadata routes (RFC 9728)."""+ # Lifecycle hook: let subclasses react to the mcp_path becoming known+ # (e.g., bind token audience to the resource URL). Mirrors the call in+ # OAuthAuthorizationServerProvider.get_routes so all providers see the+ # path at the same point in their lifecycle.+ self.set_mcp_path(mcp_path)+routes = []# Get the resource URL based on the MCP pathdiff --git a/src/fastmcp/server/auth/providers/jwt.py b/src/fastmcp/server/auth/providers/jwt.pyindex 17194329f..2417cd067 100644--- a/src/fastmcp/server/auth/providers/jwt.py+++ b/src/fastmcp/server/auth/providers/jwt.py@@ -419,13 +419,16 @@ class JWTVerifier(TokenVerifier):or "unknown")- # Validate expiration+ # Validate expiration. Kept at INFO (not WARNING like issuer/+ # audience/scope mismatches below) β expiry is expected-path noise+ # from normal token rotation, not a configuration error worth+ # surfacing by default.exp = claims.get("exp")if exp is not None and exp < time.time():- self.logger.debug(- "Token validation failed: expired token for client %s", client_id+ self.logger.info(+ "Bearer token rejected for client %s: token expired",+ client_id,)- self.logger.info("Bearer token rejected for client %s", client_id)return None# Validate issuer - note we use issuer instead of issuer_url here because@@ -443,11 +446,13 @@ class JWTVerifier(TokenVerifier):issuer_valid = iss == self.issuerif not issuer_valid:- self.logger.debug(- "Token validation failed: issuer mismatch for client %s",+ self.logger.warning(+ "Bearer token rejected for client %s: issuer mismatch "+ "(got %r, expected %r)",client_id,+ iss,+ self.issuer,)- self.logger.info("Bearer token rejected for client %s", client_id)return None# Validate audience if configured@@ -474,11 +479,13 @@ class JWTVerifier(TokenVerifier):audience_valid = aud == self.audienceif not audience_valid:- self.logger.debug(- "Token validation failed: audience mismatch for client %s",+ self.logger.warning(+ "Bearer token rejected for client %s: audience mismatch "+ "(got %r, expected %r)",client_id,+ aud,+ self.audience,)- self.logger.info("Bearer token rejected for client %s", client_id)return None# Extract scopes@@ -489,12 +496,13 @@ class JWTVerifier(TokenVerifier):token_scopes = set(scopes)required_scopes = set(self.required_scopes)if not required_scopes.issubset(token_scopes):- self.logger.debug(- "Token missing required scopes. Has: %s, Required: %s",- token_scopes,- required_scopes,+ self.logger.warning(+ "Bearer token rejected for client %s: missing required "+ "scopes (has %s, requires %s)",+ client_id,+ sorted(token_scopes),+ sorted(required_scopes),)- self.logger.info("Bearer token rejected for client %s", client_id)return Nonereturn AccessToken(diff --git a/src/fastmcp/server/auth/providers/workos.py b/src/fastmcp/server/auth/providers/workos.pyindex a29e331fb..bd6d582ad 100644--- a/src/fastmcp/server/auth/providers/workos.py+++ b/src/fastmcp/server/auth/providers/workos.py@@ -277,17 +277,22 @@ class AuthKitProvider(RemoteAuthProvider):For detailed setup instructions, see:https://workos.com/docs/authkit/mcp/integrating/token-verification+ Token audience is bound to this server automatically: when the MCP+ mount path becomes known (typically at ``http_app()`` construction),+ ``JWTVerifier.audience`` is set to the resource URL advertised in+ ``.well-known/oauth-protected-resource``. Enable Resource Indicators+ (RFC 8707) in your WorkOS Dashboard and list that same URL β AuthKit+ will then mint tokens with the matching ``aud`` claim.+Example:```pythonfrom fastmcp.server.auth.providers.workos import AuthKitProvider- # Create AuthKit metadata provider (JWT verifier created automatically)workos_auth = AuthKitProvider(authkit_domain="https://your-workos-domain.authkit.app",base_url="https://your-fastmcp-server.com",)- # Use with FastMCPmcp = FastMCP("My App", auth=workos_auth)```"""@@ -297,7 +302,7 @@ class AuthKitProvider(RemoteAuthProvider):*,authkit_domain: AnyHttpUrl | str,base_url: AnyHttpUrl | str,- client_id: str | None = None,+ resource_base_url: AnyHttpUrl | str | None = None,required_scopes: list[str] | None = None,scopes_supported: list[str] | None = None,resource_name: str | None = None,@@ -309,16 +314,20 @@ class AuthKitProvider(RemoteAuthProvider):Args:authkit_domain: Your AuthKit domain (e.g., "https://your-app.authkit.app")base_url: Public URL of this FastMCP server- client_id: Your WorkOS project client ID (e.g., "client_01ABC..."). Used to- validate the JWT audience claim. Found in your WorkOS Dashboard under- API Keys. This is the project-level client ID, not individual MCP client IDs.+ resource_base_url: Optional public base URL for the protected resource.+ When provided, this URL is advertised in protected resource metadata+ instead of ``base_url``. Useful when OAuth callbacks and the protected+ MCP resource live under different public URLs.required_scopes: Optional list of scopes to require for all requestsscopes_supported: Optional list of scopes to advertise in OAuth metadata.If None, uses required_scopes. Use this when the scopes clients shouldrequest differ from the scopes enforced on tokens.resource_name: Optional name for the protected resource metadata.resource_documentation: Optional documentation URL for the protected resource.- token_verifier: Optional token verifier. If None, creates JWT verifier for AuthKit+ token_verifier: Optional token verifier. If provided, it is used as-is and+ audience auto-wiring is skipped β the caller is responsible for setting+ an appropriate ``audience``. If None (default), a ``JWTVerifier`` is+ created with audience bound to this server's resource URL."""self.authkit_domain = str(authkit_domain).rstrip("/")self.base_url = AnyHttpUrl(str(base_url).rstrip("/"))@@ -328,19 +337,14 @@ class AuthKitProvider(RemoteAuthProvider):parse_scopes(required_scopes) if required_scopes is not None else None)- # Create default JWT verifier if none provided+ # When no custom verifier is provided, we own the JWTVerifier and can+ # bind its audience to our resource URL once set_mcp_path() is called.+ self._auto_bind_audience = token_verifier is Noneif token_verifier is None:- logger.warning(- "AuthKitProvider cannot validate token audience for the specific resource "- "because AuthKit does not support RFC 8707 resource indicators. "- "This may leave the server vulnerable to cross-server token replay. "- "Consider using WorkOSProvider (OAuth proxy) for audience-bound tokens."- )token_verifier = JWTVerifier(jwks_uri=f"{self.authkit_domain}/oauth2/jwks",issuer=self.authkit_domain,algorithm="RS256",- audience=client_id,required_scopes=parsed_scopes,)@@ -349,11 +353,34 @@ class AuthKitProvider(RemoteAuthProvider):token_verifier=token_verifier,authorization_servers=[AnyHttpUrl(self.authkit_domain)],base_url=self.base_url,+ resource_base_url=resource_base_url,scopes_supported=scopes_supported,resource_name=resource_name,resource_documentation=resource_documentation,)+ def set_mcp_path(self, mcp_path: str | None) -> None:+ """Bind the default verifier's audience to this server's resource URL.++ AuthKit with Resource Indicators (RFC 8707) mints tokens whose ``aud``+ claim equals the resource URL the client requested β which is the URL+ we advertise in ``.well-known/oauth-protected-resource``. Binding the+ audience here keeps validation in lock-step with what clients are sent.+ """+ super().set_mcp_path(mcp_path)+ if (+ self._auto_bind_audience+ and self._resource_url is not None+ and isinstance(self.token_verifier, JWTVerifier)+ ):+ resource_url = str(self._resource_url)+ self.token_verifier.audience = resource_url+ logger.info(+ "AuthKit tokens will be validated against aud=%s. "+ "Configure this URL as a Resource Indicator in the WorkOS Dashboard.",+ resource_url,+ )+def get_routes(self,mcp_path: str | None = None,diff --git a/tests/server/auth/providers/test_workos.py b/tests/server/auth/providers/test_workos.pyindex cc6ac742a..2e87956c1 100644--- a/tests/server/auth/providers/test_workos.py+++ b/tests/server/auth/providers/test_workos.py@@ -9,6 +9,7 @@ from pytest_httpx import HTTPXMockfrom fastmcp import Client, FastMCPfrom fastmcp.client.transports import StreamableHttpTransport+from fastmcp.server.auth.providers.jwt import JWTVerifierfrom fastmcp.server.auth.providers.workos import (AuthKitProvider,WorkOSProvider,@@ -173,6 +174,97 @@ class TestAuthKitProvider:# assert "add" in tools+class TestAuthKitAudienceBinding:+ """RFC 8707 resource-indicator audience binding.++ AuthKit mints tokens with ``aud`` equal to the resource URL the client+ requested β which must equal the URL FastMCP advertises in its protected+ resource metadata. AuthKitProvider auto-wires that equality: once the+ MCP mount path is known, ``JWTVerifier.audience`` is set to+ ``_get_resource_url(mcp_path)``.+ """++ def test_audience_binds_to_resource_url_on_set_mcp_path(self):+ provider = AuthKitProvider(+ authkit_domain="https://test.authkit.app",+ base_url="http://127.0.0.1:8000",+ )++ verifier = provider.token_verifier+ assert isinstance(verifier, JWTVerifier)+ # Audience unset before the path is known β provider has no way to+ # compute the resource URL yet.+ assert verifier.audience is None++ provider.set_mcp_path("/mcp")++ expected = str(provider._get_resource_url("/mcp"))+ assert verifier.audience == expected+ assert expected == "http://127.0.0.1:8000/mcp"++ def test_set_mcp_path_none_binds_to_base_url(self):+ """When no MCP path is provided, the resource URL is ``base_url``+ itself (an MCP-at-root server) and the audience binds to that."""+ provider = AuthKitProvider(+ authkit_domain="https://test.authkit.app",+ base_url="http://127.0.0.1:8000",+ )++ provider.set_mcp_path(None)++ verifier = provider.token_verifier+ assert isinstance(verifier, JWTVerifier)+ # Matches _get_resource_url(None) which returns base_url unchanged.+ assert verifier.audience == "http://127.0.0.1:8000/"++ def test_audience_respects_resource_base_url(self):+ """When ``resource_base_url`` differs from ``base_url``, the audience+ follows the advertised resource URL, not the OAuth-surface URL."""+ provider = AuthKitProvider(+ authkit_domain="https://test.authkit.app",+ base_url="https://oauth.example.com",+ resource_base_url="https://api.example.com",+ )+ provider.set_mcp_path("/mcp")++ verifier = provider.token_verifier+ assert isinstance(verifier, JWTVerifier)+ assert verifier.audience == "https://api.example.com/mcp"++ def test_custom_token_verifier_audience_not_overwritten(self):+ """If the caller supplies their own verifier, we treat its audience+ as intentional and do not touch it."""+ custom_audience = "https://some-other-resource.example.com"+ custom = JWTVerifier(+ jwks_uri="https://test.authkit.app/oauth2/jwks",+ issuer="https://test.authkit.app",+ audience=custom_audience,+ )+ provider = AuthKitProvider(+ authkit_domain="https://test.authkit.app",+ base_url="http://127.0.0.1:8000",+ token_verifier=custom,+ )+ provider.set_mcp_path("/mcp")++ assert provider.token_verifier is custom+ assert custom.audience == custom_audience++ def test_audience_binds_through_http_app(self):+ """End-to-end: mounting a FastMCP server triggers the lifecycle hook+ that populates ``JWTVerifier.audience``."""+ auth = AuthKitProvider(+ authkit_domain="https://test.authkit.app",+ base_url="http://127.0.0.1:8000",+ )+ mcp = FastMCP("test", auth=auth)+ mcp.http_app(path="/mcp")++ verifier = auth.token_verifier+ assert isinstance(verifier, JWTVerifier)+ assert verifier.audience == "http://127.0.0.1:8000/mcp"++class TestWorkOSTokenVerifierScopes:async def test_verify_token_rejects_missing_required_scopes(self, httpx_mock: HTTPXMock