MCP OAuth Troubleshooting

Implementation Reference: The authentication logic described in this page is implemented in apps/backend/src/middleware/api-key-oauth.middleware.ts.

​

Authentication Scenarios

​

1. Both API Key and OAuth Disabled

• All requests pass through without authentication
• No authentication headers required
• Suitable for public endpoints that don’t require authentication

{
  "message": "Public endpoint - no authentication required"
}

​

2. API Key Only (OAuth Disabled)

• Requires valid API key via X-API-Key header or query parameter
• Critical Issue: If API key is missing or invalid, some MCP clients (like Inspector) may attempt OAuth flow
• This can cause infinite refresh loops and 429 rate limit errors

curl -H "X-API-Key: mcp_1234567890abcdef" \
  https://your-domain.com/api/endpoint

{
  "error": "authentication_required",
  "error_description": "Authentication required via API key",
  "supported_methods": [
    "X-API-Key header",
    "query parameter (api_key or apikey)"
  ],
  "timestamp": "2024-01-01T00:00:00.000Z"
}

• Infinite token refresh attempts
• 429 “Too Many Requests” errors
• Inspector becoming unusable

​

3. Both API Key and OAuth Enabled

• Accepts both API keys and OAuth bearer tokens
• API key takes precedence if provided
• Falls back to OAuth if no API key is provided
• Most flexible configuration

1. No Token Provided: Initiates OAuth flow
   Copy

   {
     "error": "authentication_required",
     "error_description": "Authentication required via OAuth bearer token or API key",
     "supported_methods": [
       "Authorization header (Bearer token)",
       "X-API-Key header",
       "query parameter (api_key or apikey)"
     ]
   }
   

2. Valid API Key: Passes through
   Copy

   curl -H "X-API-Key: mcp_1234567890abcdef" \
     https://your-domain.com/api/endpoint
   

3. Valid OAuth Token: Passes through
   Copy

   curl -H "Authorization: Bearer mcp_token_1234567890abcdef" \
     https://your-domain.com/api/endpoint
   

4. Invalid Credentials: Returns 401 with rate limiting
   Copy

   {
     "error": "invalid_credentials",
     "error_description": "Authentication failed. Invalid credentials provided.",
     "timestamp": "2024-01-01T00:00:00.000Z"
   }
   

​

4. OAuth Only (API Key Disabled)

• Requires OAuth bearer token
• No API key support
• Clean OAuth-only authentication

curl -H "Authorization: Bearer mcp_token_1234567890abcdef" \
  https://your-domain.com/api/endpoint

{
  "error": "authentication_required",
  "error_description": "Authentication required via OAuth bearer token",
  "supported_methods": ["Authorization header (Bearer token)"],
  "WWW-Authenticate": "Bearer realm=\"MetaMCP\", scope=\"admin\""
}

{
  "error": "invalid_token",
  "error_description": "The provided OAuth token is invalid or has expired.",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

​

Common Issues and Solutions

​

Issue 1: Infinite OAuth Refresh Loop

• MCP Inspector continuously refreshes tokens
• 429 “Too Many Requests” errors
• Inspector becomes unresponsive

1. Enable OAuth in endpoint configuration:
   Copy

   {
     "enable_api_key_auth": true,
     "enable_oauth": true
   }
   

2. Configure MCP client to use API keys only:
   • Update client configuration to use X-API-Key header
   • Disable OAuth flow in client settings
3. Use OAuth-only configuration:
   Copy

   {
     "enable_api_key_auth": false,
     "enable_oauth": true
   }
   

​

Issue 2: 429 Rate Limit Errors

• “Too many failed authentication attempts” errors
• Temporary lockout from authentication attempts

1. Wait for rate limit to reset (1 minute)
2. If you have enabled Auth, make sure you never pass in a wrong API key.

​

Issue 3: Access Denied (403) Errors

• “Access denied” errors even with valid credentials
• “Public API keys cannot access private endpoints” messages

1. For Private Endpoints: Use API key owned by endpoint creator
2. For Public Endpoints: Any valid API key or OAuth token works
3. Check endpoint ownership:
   Copy

   # Get endpoint details
   curl -H "Authorization: Bearer your-token" \
     https://your-domain.com/api/endpoints/endpoint-uuid
   

​

Issue 4: Wrong Authentication Method

• “Authentication required via API key” when using OAuth
• “Authentication required via OAuth bearer token” when using API key

1. Check endpoint configuration:
   Copy

   # Get endpoint configuration
   curl -H "Authorization: Bearer your-token" \
     https://your-domain.com/api/endpoints/endpoint-uuid
   

2. Use correct authentication method:
   • API key: X-API-Key header or api_key query parameter
   • OAuth: Authorization: Bearer header