Skip to content

authentication-errors.mdx

Latest commit

 

History

History
111 lines (68 loc) · 3.33 KB

authentication-errors.mdx

File metadata and controls

111 lines (68 loc) · 3.33 KB
Raw
title Authentication errors
description Troubleshoot 401, 403, and missing credential errors.

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.

For protected remote MCP servers, the official MCP authorization specification defines the protocol-level authentication and token requirements.

0mcp uses pass-through authentication for upstream API credentials. For OAuth-protected MCP tools, the server Setup page may also require issuer configuration before client setup is usable.

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.
  4. If Setup reports an OAuth configuration issue, add the issuer and JWKS settings from server Settings.

Your upstream API logs are the best source for diagnosing detailed authentication failures.