Claude Desktop OAuth 2.1 Custom MCP Connector Fails with 401/end_error While CLI Works

If all above fixes applied and still failing, capture the ofid_ reference ID from the Claude Desktop error card and file at the correct repo (claude-ai-mcp for Desktop-specific issues, not claude-code which tracks CLI).

1. In Claude Desktop, after failed connection, look for ofid_XXXXXXXX reference ID in the error card
2. File a new issue at https://github.com/anthropics/claude-ai-mcp (NOT the claude-code repo)
3. Include: ofid_ reference, full server access logs during the attempt, DCR request/response bodies, token exchange trace, and your .well-known endpoint responses

# Capture full debug trace:
curl -v https://your-mcp-server/.well-known/oauth-authorization-server > /tmp/debug-trace.txt 2>&1
curl -v -X POST https://your-mcp-server/register -H 'Content-Type: application/json' -d '{"client_name":"debug","redirect_uris":["https://claude.ai/callback"]}' >> /tmp/debug-trace.txt 2>&1
cat /tmp/debug-trace.txt

Fix Dynamic Client Registration response to comply with RFC 7591. client_secret_expires_at must be an integer (seconds since epoch), not a float. Handle token_endpoint_auth_method downgrade for unauthenticated public clients.

1. Ensure client_secret_expires_at is returned as Math.floor(Date.now()/1000), not as a float or Date object
2. For better-auth: in registration handler, check if request is unauthenticated and downgrade token_endpoint_auth_method from client_secret_post to none
3. List all supported scopes in clientRegistrationAllowedScopes in the authorization server metadata
4. Accept callback URLs from both https://claude.ai and https://claude.com

curl -s -X POST https://your-mcp-server/register -H 'Content-Type: application/json' -d '{"client_name":"test","redirect_uris":["https://claude.ai/callback"]}' | python3 -c "import sys,json; d=json.load(sys.stdin); print('expires_at type:', type(d.get('client_secret_expires_at')).__name__, 'value:', d.get('client_secret_expires_at'))"

# Expected: expires_at type: int value: 1749600000

# Correct DCR response (RFC 7591 compliant):
{
  "client_id": "abc123",
  "client_secret": "xyz789",
  "client_secret_expires_at": 1749600000,
  "token_endpoint_auth_method": "none"
}

# better-auth downgrade patch:
if (!ctx.session && body.token_endpoint_auth_method === 'client_secret_post') {
  body.token_endpoint_auth_method = 'none';
}

Well-known OAuth endpoints must serve permissive CORS headers and handle OPTIONS preflight for browser-based Claude clients. Note: Access-Control-Allow-Origin: * is appropriate ONLY for public .well-known endpoints, not the MCP endpoint itself.

1. Serve Access-Control-Allow-Origin: * on /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource (these are public discovery endpoints, no secrets exposed)
2. Add OPTIONS preflight handler returning 204 with Access-Control-Allow-Methods: GET, POST, OPTIONS
3. Include MCP-Protocol-Version and Mcp-Session-Id in Access-Control-Allow-Headers
4. Add Cache-Control: private, no-store, no-cache, must-revalidate, max-age=0 on well-known responses to prevent CDN caching of auth metadata
5. IMPORTANT: The MCP endpoint (/mcp) itself should use a specific origin, not *

curl -v -X OPTIONS https://your-mcp-server/.well-known/oauth-authorization-server 2>&1 | grep -E '(HTTP/|Access-Control)'

# Expected: HTTP/2 204 with Access-Control-Allow-Origin: *

# Express.js CORS for well-known endpoints:
app.use('/.well-known', (req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, MCP-Protocol-Version, Mcp-Session-Id');
  res.setHeader('Cache-Control', 'private, no-store, no-cache, must-revalidate, max-age=0');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

Claude Desktop requires WWW-Authenticate header on 401 responses for OAuth discovery. The header must also be listed in Access-Control-Expose-Headers for browser-based clients. This is the most common single-point fix.

1. On the MCP POST endpoint, when returning 401, include response header: WWW-Authenticate: Bearer
2. Add WWW-Authenticate to Access-Control-Expose-Headers response header
3. Also include MCP-Protocol-Version and Mcp-Session-Id in Access-Control-Allow-Headers

curl -v -X POST https://your-mcp-server/mcp -H 'Content-Type: application/json' -d '{}' 2>&1 | grep -i 'www-authenticate'

# Expected: < WWW-Authenticate: Bearer

# Express.js middleware:
app.post('/mcp', (req, res) => {
  if (!req.headers.authorization) {
    res.setHeader('WWW-Authenticate', 'Bearer');
    res.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate');
    return res.status(401).json({ error: 'unauthorized' });
  }
  // ... handle MCP request
});

# Cloudflare Worker:
export default {
  async fetch(request) {
    if (!request.headers.get('Authorization')) {
      return new Response(JSON.stringify({ error: 'unauthorized' }), {
        status: 401,
        headers: {
          'WWW-Authenticate': 'Bearer',
          'Access-Control-Expose-Headers': 'WWW-Authenticate',
          'Content-Type': 'application/json'
        }
      });
    }
  }
}

Add WAF custom rule to skip security checks for requests with User-Agent containing Claude. Allow Anthropic outbound IP ranges. For Cloudflare Workers MCP servers, create KV namespace for OAuth state.

1. In Cloudflare Dashboard > Security > WAF > Custom Rules, create rule: (http.user_agent contains "Claude") -> Skip (all remaining custom rules)
2. Add Anthropic outbound IP ranges to firewall allowlist from https://docs.anthropic.com/en/api/ip-addresses
3. For Cloudflare Workers: in Dashboard > Workers & Pages > [your-worker] > Settings > Variables, add KV namespace binding: variable name MCP_DATA, select your KV namespace

curl -s https://docs.anthropic.com/en/api/ip-addresses | grep -oP '\d+\.\d+\.\d+\.\d+/\d+' | while read ip; do ufw allow from $ip; done

# Cloudflare WAF Custom Rule Expression:
(http.user_agent contains "Claude")

# Cloudflare Workers wrangler.toml:
[[kv_namespaces]]
binding = "MCP_DATA"
id = "<your-kv-namespace-id>"