Skip to main content
Authentication errors usually happen when your upstream API doesn’t receive the credentials it expects, or when the provided credentials don’t have permission to access the requested operation.

​
Common error types

​
401 Unauthorized

A 401 response usually means:
  • A credential is missing
  • The token or API key is invalid
  • The token has expired
  • The required authentication header wasn’t sent correctly

​
403 Forbidden

A 403 response usually means:
  • The credential is valid
  • It doesn’t have permission to access the requested API operation
This often happens when the token lacks the required scopes, roles, or access policies.
A 401 usually points to credential identity or formatting. A 403 usually points to permission.

​
Quick checks

​
Verify the client configuration

Open the Setup page and confirm that:
  • All required headers are configured
  • Environment variables are correctly named
  • Credentials are being passed to the client

​
Check Bearer token formatting

If your API uses Bearer authentication, make sure the value includes the required prefix: 
Authorization: Bearer YOUR_TOKEN

​
Verify API key header names

Header names must match exactly, including capitalization, spelling, and dashes. Example: 
X-API-Key: YOUR_API_KEY

​
Replace expired credentials

Ensure the token or API key:
  • Has not expired
  • Has not been revoked
  • Is still active in your upstream system

​
Confirm permissions

Verify that the credential is allowed to access the selected API operation. A valid token can still return 403 Forbidden if it lacks the required permissions.

​
Reconnect the client

After updating environment variables or credentials:
  • Restart the MCP client
  • Or reconnect the server
Some clients cache configuration until restarted.

​
Query API keys

If your API expects authentication as a query parameter:
  • Use the gateway header provided by 0mcp
  • Do not place secrets directly in the MCP endpoint URL
0mcp automatically converts the secure header into the required query parameter before forwarding the request upstream.
Never add an API key directly to the MCP endpoint URL or commit it to a shared client configuration.
Read the authentication model for details about pass-through credentials and supported methods.

​
Still not working?

To continue debugging:
  1. Review the failed request in Logs.
  2. Compare the timestamp with your upstream API logs.
  3. Confirm your OpenAPI security scheme matches your actual API authentication requirements.
Your upstream API logs are the best source for diagnosing detailed authentication failures.