Skip to main content
New in version: 2.12.4 OIDC Proxy enables FastMCP servers to authenticate with OIDC providers that don’t support Dynamic Client Registration (DCR) out of the box. This includes OAuth providers like: Auth0, Google, Azure, AWS, etc. For providers that do support DCR (like WorkOS AuthKit), use RemoteAuthProvider instead. The OIDC Proxy is built upon OAuthProxy so it has all the same functionality under the covers.

​
Implementation

​
Provider Setup Requirements

Before using OIDC Proxy, you need to register your application with your OAuth provider:
  1. Register your application in the provider’s developer console (Auth0 Applications, Google Cloud Console, Azure Portal, etc.)
  2. Configure the redirect URI as your FastMCP server URL plus your chosen callback path:
    • Default: https://your-server.com/auth/callback
    • Custom: https://your-server.com/your/custom/path (if you set redirect_path)
    • Development: http://localhost:8000/auth/callback
  3. Obtain your credentials: Client ID and Client Secret
The redirect URI you configure with your provider must exactly match your FastMCP server’s URL plus the callback path. If you customize redirect_path in OAuth Proxy, update your provider’s redirect URI accordingly.

​
Basic Setup

Here’s how to implement OIDC Proxy with any provider: 
from fastmcp import FastMCP
from fastmcp.server.auth.oidc_proxy import OIDCProxy

# Create the OIDC proxy
auth = OIDCProxy(
    # Provider's configuration URL
    config_url="https://provider.com/.well-known/openid-configuration",

    # Your registered app credentials
    client_id="your-client-id",
    client_secret="your-client-secret",

    # Your FastMCP server's public URL
    base_url="https://your-server.com",

    # Optional: customize the callback path (default is "/auth/callback")
    # redirect_path="/custom/callback",
)

mcp = FastMCP(name="My Server", auth=auth)

​
Configuration Parameters

OIDCProxy Parameters

​
config_url
str
required
URL of your OAuth provider’s OIDC configuration
​
client_id
str
required
Client ID from your registered OAuth application
​
client_secret
str
required
Client secret from your registered OAuth application
​
base_url
AnyHttpUrl | str
required
Public URL of your FastMCP server (e.g., https://your-server.com)
​
strict
bool | None
Strict flag for configuration validation. When True, requires all OIDC mandatory fields.
​
audience
str | None
Audience parameter for OIDC providers that require it (e.g., Auth0). This is typically your API identifier.
​
timeout_seconds
int | None
default:"10"
HTTP request timeout in seconds for fetching OIDC configuration
​
algorithm
str | None
JWT algorithm to use for token verification (e.g., “RS256”). If not specified, uses the provider’s default.
​
required_scopes
list[str] | None
List of OAuth scopes to request from the provider. These are automatically included in authorization requests.
​
redirect_path
str
default:"/auth/callback"
Path for OAuth callbacks. Must match the redirect URI configured in your OAuth application
​
allowed_client_redirect_uris
list[str] | None
List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g., "http://localhost:*", "https://*.example.com/*").
  • None (default): All redirect URIs allowed (for MCP/DCR compatibility)
  • Empty list []: No redirect URIs allowed
  • Custom list: Only matching patterns allowed
These patterns apply to MCP client loopback redirects, NOT the upstream OAuth app redirect URI.
​
token_endpoint_auth_method
str | None
Token endpoint authentication method for the upstream OAuth server. Controls how the proxy authenticates when exchanging authorization codes and refresh tokens with the upstream provider.
  • "client_secret_basic": Send credentials in Authorization header (most common)
  • "client_secret_post": Send credentials in request body (required by some providers)
  • "none": No authentication (for public clients)
  • None (default): Uses authlib’s default (typically "client_secret_basic")
Set this if your provider requires a specific authentication method and the default doesn’t work.
​
client_storage
KVStorage | None
Storage backend for persisting OAuth client registrations. By default, clients are automatically persisted to disk in ~/.config/fastmcp/oidc-proxy-clients/, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly after your server restarts.
from fastmcp.utilities.storage import InMemoryStorage

# Use in-memory storage for testing (clients lost on restart)
auth = OIDCProxy(..., client_storage=InMemoryStorage())

​
Using Built-in Providers

FastMCP includes pre-configured OIDC providers for common services: 
from fastmcp.server.auth.providers.auth0 import Auth0Provider

auth = Auth0Provider(
    config_url="https://.../.well-known/openid-configuration",
    client_id="your-auth0-client-id",
    client_secret="your-auth0-client-secret",
    audience="https://...",
    base_url="https://localhost:8000"
)

mcp = FastMCP(name="My Server", auth=auth)
Available providers include Auth0Provider at present.

​
Scope Configuration

OAuth scopes are configured with required_scopes to automatically request the permissions your application needs. Dynamic clients created by the proxy will automatically include these scopes in their authorization requests.

​
Environment Configuration

New in version: 2.13.0 For production deployments, configure OIDC Proxy through environment variables instead of hardcoding credentials: 
# Specify the provider implementation
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.auth0.Auth0Provider

# Provider-specific credentials
export FASTMCP_SERVER_AUTH_AUTH0_CONFIG_URL=https://.../.well-known/openid-configuration
export FASTMCP_SERVER_AUTH_AUTH0_CLIENT_ID=tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB
export FASTMCP_SERVER_AUTH_AUTH0_CLIENT_SECRET=vPYqbjemq...
export FASTMCP_SERVER_AUTH_AUTH0_AUDIENCE=https://...
export FASTMCP_SERVER_AUTH_AUTH0_BASE_URL=https://localhost:8000
With environment configuration, your server code simplifies to: 
from fastmcp import FastMCP

# Authentication automatically configured from environment
mcp = FastMCP(name="My Server")

@mcp.tool
def protected_tool(data: str) -> str:
    """This tool is now protected by OAuth."""
    return f"Processed: {data}"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)
⌘I