Authentication

​

Choosing an Authentication Method

​

Understanding the Two OAuth Patterns

• What you’re building: A new integration where you store and manage user data
• How it works: Use an identity provider like WorkOS AuthKit to handle the OAuth server (they manage user accounts, tokens, sessions)
• Your responsibility: Build your tools and validate tokens from the IdP
• MCP clients: Can register automatically (Dynamic Client Registration)
• Example: See the Bookmark Manager for a complete implementation where users save personal bookmarks to your database

• What you’re building: An integration that wraps an existing API with existing OAuth
• How it works: Your MCP server acts as a bridge between Poke and the upstream OAuth provider
• Your responsibility: Create an OAuth app in the provider’s dashboard, configure FastMCP’s proxy, validate upstream tokens
• MCP clients: Connect through your server’s proxy (your server handles the DCR part)
• Example: See the WHOOP Integration where users authenticate with WHOOP and you fetch their health data

​

OAuth 2.1 with PKCE

• Remote OAuth with DCR: An identity provider (WorkOS, Auth0) handles authentication for your new service
• OAuth Proxy: You proxy through to an existing service’s OAuth provider (WHOOP, GitHub, etc.)

​

What Poke Does as a Client (Same for Both Patterns)

1. Discovers your OAuth config via the .well-known endpoint
2. Handles PKCE flow (generates code_verifier and code_challenge)
3. Redirects users to your authorization URL
4. Exchanges authorization codes for tokens
5. Stores tokens securely (encrypted at rest)
6. Refreshes tokens automatically before expiration
7. Includes tokens in every request via Authorization: Bearer header

​

Complete OAuth Flow

• RFC 9728 (Protected Resource Metadata) for authorization server discovery
• RFC 8414 (Authorization Server Metadata) for endpoint discovery
• RFC 7591 (Dynamic Client Registration) when your server supports it
• PKCE with S256 (mandatory per MCP spec) for authorization code protection
• Resource parameter (RFC 8707) to bind tokens to your specific server

​

FastMCP OAuth Implementations

​

For New Services: AuthKitProvider (Remote OAuth with DCR)

from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import AuthKitProvider

auth = AuthKitProvider(
    authkit_domain="https://your-project.authkit.app",
    base_url="https://your-server.com"
)

mcp = FastMCP("Bookmark Manager", auth=auth)

@mcp.tool(description="Add bookmark for authenticated user")
async def add_bookmark(url: str, title: str) -> dict:
    # Get authenticated user's token claims
    token = get_access_token()
    user_id = token.claims["sub"]

    # Store bookmark scoped to this user
    return save_bookmark(user_id, url, title)

• JWT token validation via JWKS
• Protected resource metadata (/.well-known/oauth-protected-resource)
• Authorization server discovery
• User identity via token claims

​

For Existing Services: OAuthProxy

from fastmcp import FastMCP
from fastmcp.server.auth import OAuthProxy

auth = OAuthProxy(
    upstream_authorization_endpoint="https://api.whoop.com/oauth/oauth2/auth",
    upstream_token_endpoint="https://api.whoop.com/oauth/oauth2/token",
    upstream_client_id=os.environ["WHOOP_CLIENT_ID"],
    upstream_client_secret=os.environ["WHOOP_CLIENT_SECRET"],
    forward_pkce=True,
    base_url=os.environ["PUBLIC_BASE_URL"]
)

mcp = FastMCP("WHOOP Integration", auth=auth)

@mcp.tool(description="Get user's WHOOP recovery data")
async def get_recovery() -> dict:
    # Get token to call upstream WHOOP API
    token = get_access_token()

    # Call WHOOP API with user's token
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.whoop.com/developer/v2/recovery",
            headers={"Authorization": f"Bearer {token.token}"}
        )
        return response.json()

• Proxying OAuth flow to upstream provider
• PKCE between Poke and your server, and your server and upstream
• Token exchange with upstream provider
• Exposing MCP-compatible discovery endpoints

​

OAuth Discovery: What Poke Expects

​

1. Protected Resource Metadata

{
  "resource": "https://your-server.com",
  "authorization_servers": ["https://auth.your-server.com"]
}

​

2. Authorization Server Metadata

{
  "issuer": "https://auth.your-server.com",
  "authorization_endpoint": "https://auth.your-server.com/authorize",
  "token_endpoint": "https://auth.your-server.com/token",
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "response_types_supported": ["code"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post"]
}

​

Token Validation

from fastmcp import FastMCP

mcp = FastMCP("My Service", auth=oauth_config)

# FastMCP automatically validates tokens
# Rejects requests with invalid/expired tokens with 401
# Provides authenticated context to your tools

1. Verify token signature (if using JWT)
2. Check expiration (exp claim)
3. Validate audience (token issued for your server)
4. Verify scopes (user authorized required permissions)
5. Return 401 if any check fails

​

Token Refresh

POST /token HTTP/1.1
Host: auth.your-server.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<refresh_token>&
client_id=<client_id>&
resource=https://your-server.com

{
  "access_token": "new_token",
  "refresh_token": "new_refresh_token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

​

When Users Should See OAuth

• First connection: User hasn’t authorized your integration yet
• Token expired: Refresh token is invalid/expired, requires reauthorization
• Scope changes: You request additional permissions

​

API Key Authentication

​

What You Build

from fastmcp import FastMCP
import os

mcp = FastMCP("My Service")

@mcp.tool(description="Get user data")
async def get_data() -> dict:
    # Access API key from request context
    api_key = mcp.get_auth_header()

    # Validate against your backend
    user = await validate_api_key(api_key)
    if not user:
        raise ValueError("Invalid API key")

    return fetch_user_data(user.id)

​

What Poke Does

1. User pastes API key in Poke’s connection form
2. Poke tests connection by calling your server with Authorization: Bearer <key>
3. If validation succeeds, integration is connected
4. Every subsequent request includes the same header

​

Request Format

POST /mcp HTTP/1.1
Host: your-server.com
Authorization: Bearer sk_your_api_key_here
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { ... }
}

​

Validation Best Practices

• Validate keys on every request
• Return 401 for invalid/expired keys
• Rate limit by API key
• Support key rotation (users can update keys in Poke)

• Accept keys in URL query parameters (security risk)
• Log API keys (store hashed versions)
• Return detailed error messages (prevents enumeration attacks)

​

When to Use API Keys

• Developer/power user integrations
• Services with existing API key infrastructure
• Testing and development environments
• Read-only or low-risk operations

• Consumer-facing apps (OAuth is better UX)
• High-security requirements (keys don’t expire)
• Per-user data access (hard to manage at scale)

​

No Authentication

​

What You Build

from fastmcp import FastMCP
import httpx

mcp = FastMCP("Public Data Service")

@mcp.tool(description="Get current weather")
async def get_weather(city: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.weather.com/v1/current?city={city}"
        )
        return response.json()

​

What Poke Does

1. User enters server URL
2. Poke connects immediately (no auth prompt)
3. Tools are available for all users

​

When to Use No Auth

• Public APIs (weather, astronomy, public datasets)
• Read-only data that’s not sensitive
• Internal tools within trusted networks
• Testing and demos

• Rate limit by IP to prevent abuse
• Monitor usage patterns for anomalies
• Consider API keys if abuse occurs
• Document public endpoints clearly

​

Security Best Practices

​

For All Authentication Methods

1. Use HTTPS everywhere (required by MCP spec for production)
2. Validate all inputs before processing requests
3. Rate limit requests to prevent abuse
4. Log authentication failures for monitoring
5. Rotate secrets regularly (OAuth secrets, API keys, encryption keys)

​

OAuth-Specific

1. Implement PKCE (mandatory for public clients)
2. Validate state parameter to prevent CSRF attacks
3. Bind tokens to audience (verify tokens are for your server)
4. Issue short-lived access tokens (15-60 minutes recommended)
5. Rotate refresh tokens on each use
6. Never pass through tokens to third-party APIs (see MCP Security Best Practices)

​

API Key-Specific

1. Hash keys in database (don’t store plaintext)
2. Use cryptographically secure random generation (e.g., secrets.token_urlsafe())
3. Prefix keys with identifiable strings (e.g., sk_live_, sk_test_)
4. Implement key expiration if possible
5. Allow users to revoke keys easily

​

No Auth-Specific

1. Rate limit aggressively (per IP, per user agent)
2. Cache responses to reduce load
3. Monitor for scraping (unusual access patterns)
4. Implement CORS properly if browser-based
5. Document acceptable use clearly

​

Testing Authentication

​

OAuth Testing

# Use MCP Inspector for local OAuth testing
npm install -g @modelcontextprotocol/inspector
mcp-inspector --config your-server-config.json

1. Deploy to HTTPS endpoint (OAuth requires secure redirects)
2. Test full flow in Poke’s integration tester
3. Verify token refresh works correctly
4. Test error cases (denied access, expired tokens)

​

API Key Testing

# Test valid key
curl -H "Authorization: Bearer sk_test_valid_key" \
     https://your-server.com/mcp

# Test invalid key (should return 401)
curl -H "Authorization: Bearer sk_test_invalid_key" \
     https://your-server.com/mcp

​

No Auth Testing

# Should work without Authorization header
curl https://your-server.com/mcp

​

How Authentication Interacts with Tool Lifecycle

• Tools discovered once after successful authentication
• Auth credentials used for all subsequent tool calls
• Reconnection required if auth changes (new scopes, new key)
• Token refresh transparent to tool execution

​

Next Steps