AuthKit: auto-bind token audience to resource URL (RFC 8707) (#3905)

Author: jlowin

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
+
 ### Prerequisites
 
 Before 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>
 
-    ![Enable Dynamic Client Registration](./images/authkit/enable_dcr.png)
+<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 the
 from fastmcp import FastMCP
 from 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.
+
 ## Testing
 
 To 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 asyncio
 auth = 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 variables
 auth = 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)

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
+   ```

examples/auth/authkit_dcr/client.py examples/auth/authkit/client.pyexamples/auth/authkit_dcr/client.py renamed to examples/auth/authkit/client.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 @@
 
 auth = 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.tool

examples/auth/authkit_dcr/server.py examples/auth/authkit/server.pyexamples/auth/authkit_dcr/server.py renamed to examples/auth/authkit/server.py

@@ -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 Prefix
 

examples/auth/authkit_dcr/README.md

@@ -10,7 +10,7 @@
 
 from fastmcp.client import Client
 
-SERVER_URL = "http://localhost:8000/mcp"
+SERVER_URL = "http://127.0.0.1:8000/mcp"
 
 
 async def main():

examples/auth/aws_oauth/README.md

@@ -31,7 +31,7 @@
     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"
 )
 

examples/auth/aws_oauth/client.py

@@ -10,7 +10,7 @@ This example demonstrates how to use the Azure OAuth provider with FastMCP serve
 2. 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) ID

examples/auth/aws_oauth/server.py

@@ -24,7 +24,7 @@
     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"])