Multiple Authentication Headers¶

Overview¶

ContextForge supports multiple custom authentication headers for both gateway connections and REST tools. This feature allows you to configure multiple header key-value pairs that will be sent with every request to your MCP servers or REST endpoints.

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¶

1. Navigate to the Admin Panel (see Admin UI URL above)
2. Click on the "Gateways" tab

3. When adding or editing a gateway:

4. Select "Custom Headers" as the Authentication Type

5. Click "Add Header" to add multiple header pairs
6. Enter the header key (e.g., X-API-Key) and value for each header
7. Click "Remove" next to any header to delete it
8. 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"}
    ]
)

Tools¶

REST tools accept the same auth_headers array on POST /tools and PUT /tools/{tool_id}, with identical validation and precedence rules:

{
  "name": "my-tool",
  "url": "https://api.example.com/endpoint",
  "request_type": "POST",
  "auth_type": "authheaders",
  "auth_headers": [
    {"key": "X-API-Key", "value": "secret"},
    {"key": "X-Tenant", "value": "acme"}
  ]
}

The same array is used by the "Custom Headers" authentication type in the Tools tab of the Admin UI.

Backward Compatibility¶

Gateways and tools still support 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¶

Gateways, tools and A2A agents share a single validator, so the same rules apply everywhere:

• Empty header keys are ignored; if no entry has a key, the request is rejected with a 422
• Header keys may contain only alphanumeric characters, hyphens and underscores — anything else (including embedded spaces) is rejected with a 422
• Surrounding whitespace on a header key is trimmed before storage
• Duplicate header keys will use the last provided value
• Header keys and values must be strings; any other JSON type is rejected with a 422
• Header values can be empty strings if required by your authentication scheme, and may contain special characters
• A maximum of 100 header entries may be submitted. The cap applies to the entries you send, before duplicates collapse — so 101 entries are rejected even if they resolve to fewer unique keys

Best Practices¶

1. Use HTTPS: Always use HTTPS URLs for your MCP servers to prevent header interception
2. Rotate Keys: Regularly rotate your API keys and update them in the gateway configuration
3. Minimal Headers: Only include headers that are strictly necessary for authentication
4. 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¶

1. Check that your gateway is using auth_type: "authheaders"
2. Verify headers are properly formatted in the JSON array
3. Ensure the gateway is enabled and reachable
4. 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:

1. Edit your gateway in the Admin UI
2. Your existing single header will be displayed
3. Add additional headers as needed
4. 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},
        ...
    ]
}

ToolCreate / ToolUpdate Schema¶

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

Related Documentation¶

• Gateway Authentication
• Security Best Practices
• Multi-Auth Headers