mcp-auth-oauth

MCP Auth — OAuth 2.1

Remote MCP servers use OAuth 2.1 + PKCE with Dynamic Client Registration. Any spec-compliant MCP client — Claude Desktop, Claude Code, Cursor, ChatGPT Apps — can authenticate users without hardcoded client IDs.

When to Use

• Building a remote MCP server that serves multiple users
• Migrating a static-bearer-token server to per-user auth
• Debugging "401 Unauthorized" or "failed to authenticate" in an MCP client
• Adding scope-based permission to an MCP server

The Flow (RFC 8414 + RFC 7591 + PKCE)

1. Client connects to MCP server → server returns 401 with WWW-Authenticate pointing to the authorization server metadata URL
2. Client fetches /.well-known/oauth-authorization-server → gets authorization_endpoint, token_endpoint, registration_endpoint
3. Client POSTs to registration_endpoint (RFC 7591) → receives a client_id dynamically
4. Client opens browser to authorization_endpoint with PKCE challenge → user approves
5. Client exchanges code at token_endpoint → receives access + refresh tokens
6. Client retries MCP request with Authorization: Bearer <token>

No pre-shared client ID. No manual app registration. The user just clicks "Allow" in a browser.

Server-Side Requirements

1. Return discovery metadata

// GET /.well-known/oauth-authorization-server
app.get("/.well-known/oauth-authorization-server", (req, res) => {
  res.json({
    issuer: "https://mcp.example.com",
    authorization_endpoint: "https://mcp.example.com/oauth/authorize",
    token_endpoint: "https://mcp.example.com/oauth/token",
    registration_endpoint: "https://mcp.example.com/oauth/register",
    scopes_supported: ["read:issues", "write:issues"],
    response_types_supported: ["code"],
    grant_types_supported: ["authorization_code", "refresh_token"],
    code_challenge_methods_supported: ["S256"],
    token_endpoint_auth_methods_supported: ["none"], // public clients
  });
});

2. 401 with WWW-Authenticate

app.use("/mcp", (req, res, next) => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token || !verifyJwt(token)) {
    res.setHeader(
      "WWW-Authenticate",
      `Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"`,
    );
    return res.status(401).json({ error: "unauthorized" });
  }
  req.user = decodeJwt(token);
  next();
});