Multiple Authentication Headers¶

Overview¶

MCP Gateway now supports multiple custom authentication headers for gateway connections. This feature allows you to configure multiple header key-value pairs that will be sent with every request to your MCP servers.

Use Cases¶

Multiple authentication headers are useful when: - Your MCP server requires multiple API keys or tokens - You need to send client identification along with authentication - Your service uses region-specific or version-specific headers - You're integrating with services that require complex header-based authentication

Configuration¶

Via Admin UI¶

Navigate to the Admin Panel at http://localhost:8000/admin/
Click on the "Gateways" tab
When adding or editing a gateway:
Select "Custom Headers" as the Authentication Type
Click "Add Header" to add multiple header pairs
Enter the header key (e.g., X-API-Key) and value for each header
Click "Remove" next to any header to delete it
Submit the form to save your configuration

Via API¶

Send a POST request to /admin/gateways with the auth_headers field as a JSON array:

{
  "name": "My Gateway",
  "url": "http://mcp-server.example.com",
  "auth_type": "authheaders",
  "auth_headers": [
    {"key": "X-API-Key", "value": "secret-key-123"},
    {"key": "X-Client-ID", "value": "client-456"},
    {"key": "X-Region", "value": "us-east-1"}
  ]
}

Via Python SDK¶

from mcpgateway.schemas import GatewayCreate

gateway = GatewayCreate(
    name="My Gateway",
    url="http://mcp-server.example.com",
    auth_type="authheaders",
    auth_headers=[
        {"key": "X-API-Key", "value": "secret-key-123"},
        {"key": "X-Client-ID", "value": "client-456"},
        {"key": "X-Region", "value": "us-east-1"}
    ]
)

Backward Compatibility¶

The gateway still supports the legacy single-header format for backward compatibility:

{
  "name": "My Gateway",
  "url": "http://mcp-server.example.com",
  "auth_type": "authheaders",
  "auth_header_key": "X-API-Key",
  "auth_header_value": "secret-key-123"
}

If both auth_headers (multi) and auth_header_key/auth_header_value (single) are provided, the multi-header format takes precedence.

Security Considerations¶

Encryption¶

All authentication headers are encrypted before being stored in the database using AES-256-GCM encryption. The encryption key is derived from the AUTH_ENCRYPTION_SECRET environment variable.

Header Validation¶

Empty header keys are ignored
Duplicate header keys will use the last provided value
Header values can be empty strings if required by your authentication scheme
Special characters in header keys and values are supported

Best Practices¶

Use HTTPS: Always use HTTPS URLs for your MCP servers to prevent header interception
Rotate Keys: Regularly rotate your API keys and update them in the gateway configuration
Minimal Headers: Only include headers that are strictly necessary for authentication
Environment Variables: Store sensitive values in environment variables when deploying

Common Patterns¶

Multiple API Keys¶

{
  "auth_headers": [
    {"key": "X-Primary-Key", "value": "primary-secret"},
    {"key": "X-Secondary-Key", "value": "secondary-secret"}
  ]
}

API Key with Client Identification¶

{
  "auth_headers": [
    {"key": "X-API-Key", "value": "api-secret"},
    {"key": "X-Client-ID", "value": "client-123"},
    {"key": "X-Client-Secret", "value": "client-secret"}
  ]
}

Regional Configuration¶

{
  "auth_headers": [
    {"key": "X-API-Key", "value": "api-secret"},
    {"key": "X-Region", "value": "eu-west-1"},
    {"key": "X-Environment", "value": "production"}
  ]
}

Troubleshooting¶

Headers Not Being Sent¶

Check that your gateway is using auth_type: "authheaders"
Verify headers are properly formatted in the JSON array
Ensure the gateway is enabled and reachable
Check server logs to confirm headers are being received

Case Sensitivity¶

HTTP headers are case-insensitive by specification. Some HTTP clients or servers may normalize header names to lowercase. Your MCP server should handle headers in a case-insensitive manner.

Validation Errors¶

If you receive validation errors when saving: - Ensure at least one header is provided when using "Custom Headers" authentication - Check that your JSON is properly formatted if using the API - Verify that header keys don't contain invalid characters

Testing Your Configuration¶

Use the "Test" button in the Admin UI to verify your gateway connection with the configured headers. The test will attempt to connect to your MCP server and validate that authentication is working correctly.

Migration from Single Headers¶

If you have existing gateways using single header authentication, they will continue to work without modification. To migrate to multi-headers:

Edit your gateway in the Admin UI
Your existing single header will be displayed
Add additional headers as needed
Save the configuration

The system will automatically convert your configuration to the multi-header format while preserving your existing authentication.

API Reference¶

GatewayCreate Schema¶

{
    "name": str,
    "url": str,
    "auth_type": "authheaders",
    "auth_headers": [
        {"key": str, "value": str},
        ...
    ]
}

GatewayUpdate Schema¶

{
    "auth_type": "authheaders",
    "auth_headers": [
        {"key": str, "value": str},
        ...
    ]
}