mcp: Instructions file for Claude Code

MCP Server Project

Critical Knowledge: MCP OAuth 2.1 Authentication

This is NOT in Claude's training data - MCP OAuth 2.1 was finalized in March 2025.

Key Insight: MCP Server = Federated OAuth 2.1 Server

The MCP server itself MUST serve .well-known/oauth-authorization-server. It acts as:

• OAuth CLIENT to upstream provider (WorkOS, GitHub, Auth0, etc.)
• OAuth SERVER to MCP clients (Claude, ChatGPT, etc.)

The MCP server issues its OWN tokens to MCP clients after authenticating users via the upstream provider.

Required Endpoints (served by MCP server)

/.well-known/oauth-authorization-server  # RFC 8414 - Discovery
/.well-known/oauth-protected-resource    # RFC 9728 - Resource metadata
/authorize                                # Start OAuth flow
/token                                    # Token exchange
/register                                 # Dynamic client registration (RFC 7591)

Flow Diagram

MCP Client (Claude/ChatGPT)
    │
    ├─► GET /.well-known/oauth-authorization-server
    │   └── Returns: { authorization_endpoint, token_endpoint, ... }
    │
    ├─► GET /authorize?client_id=...&code_challenge=...
    │   │
    │   └──► MCP Server redirects to WorkOS/GitHub/etc
    │        │
    │        └──► User authenticates
    │             │
    │             └──► Callback to MCP server
    │                  │
    │                  └──► MCP server issues its OWN auth code
    │
    ├─► POST /token (exchange code for MCP server's tokens)
    │
    └─► Use token for MCP requests

---

Implementation Options

Option 1: @cloudflare/workers-oauth-provider

import { OAuthProvider } from '@cloudflare/workers-oauth-provider'

export default new OAuthProvider({
  apiRoute: "/",
  apiHandler: MyMCP.serve("/"),
  defaultHandler: WorkOSHandler,
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
});

Storage: KV only (hardcoded OAUTH_KV binding)

• Client registrations: client:{clientId}
• Grants: grant:{userId}:{grantId}
• Tokens: token:{userId}:{grantId}:{tokenId}