Skip to main content
For MCP servers that don’t use standard OAuth, configure custom authentication with headers. Use this for API key-based services, internal servers with static tokens, or any server expecting specific headers.

​
When to Use

Custom auth is for MCP servers where:
  • Authentication uses API keys instead of OAuth
  • Internal servers use static tokens
  • The server expects specific headers for authorization
  • You want shared credentials (all users use the same authentication)

​
Static Headers

Configure headers that Portkey includes with every request to the MCP server. 
{
  "headers": {
    "Authorization": "Bearer your_api_key",
    "X-API-Key": "your_key"
  }
}
All requests to this MCP server include these headers. All users share the same credentials.

​
Common Patterns

Bearer token: 
{
  "headers": {
    "Authorization": "Bearer sk_live_xxx"
  }
}
API key header: 
{
  "headers": {
    "X-API-Key": "your_api_key"
  }
}
Basic authentication: 
{
  "headers": {
    "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
  }
}
Multiple headers: 
{
  "headers": {
    "Authorization": "Bearer api_key",
    "X-Custom-Auth": "additional_token"
  }
}

​
Passthrough Headers

Add static metadata headers separate from authentication: 
{
  "passthrough_headers": {
    "X-API-Version": "2024-01",
    "X-Client": "portkey-gateway"
  }
}
These are included alongside auth headers. Use for:
  • API versioning
  • Client identification
  • Metadata the server expects

​
Header Merge Order

When multiple header sources are configured, they merge in this order (later values override earlier):
PrioritySourceDescription
1 (lowest)Forwarded headersHeaders from agent requests (via forward_headers)
2Auth headersheaders configured on the MCP server
3Passthrough headerspassthrough_headers configured on the server
4 (highest)Identity headersHeaders from identity forwarding
What this means:
  • Auth headers override anything forwarded from agents
  • Passthrough headers override auth headers if there’s a conflict
  • Identity headers always win (prevents spoofing)
Example conflict: 
Agent sends:           X-Custom: agent-value
Server auth headers:   X-Custom: auth-value
Result: MCP server receives X-Custom: auth-value (auth headers take precedence).

​
Combining with Forwarded Headers

Combine static headers with forwarded headers: 
{
  "headers": {
    "Authorization": "Bearer api_key_xxx"
  },
  "passthrough_headers": {
    "X-API-Version": "v2"
  },
  "forward_headers": ["x-request-id", "x-trace-id"]
}
Every request to the MCP server includes:
  • Authorization: Bearer api_key_xxx (authentication)
  • X-API-Version: v2 (static metadata)
  • x-request-id and x-trace-id (from agent, if provided)
This is useful for:
  • Shared authentication to the MCP server
  • Distributed tracing from agents
  • Consistent API versioning

​
Complete Configuration Example

Full server configuration combining all header features: 
{
  "mcp_integration_details": {
    "transport": "http",
    "auth_type": "custom",
    
    "configurations": {
      "headers": {
        "Authorization": "Bearer sk_live_xxx"
      },
      "passthrough_headers": {
        "X-API-Version": "2024-01",
        "X-Client-ID": "portkey-mcp-gateway"
      },
      "forward_headers": ["x-request-id", "x-correlation-id", "x-tenant-id"],
      "user_identity_forwarding": {
        "method": "claims_header",
        "include_claims": ["sub", "email", "workspace_id"]
      }
    }
  }
}
Result for each request:
HeaderSourceValue
AuthorizationAuth headersBearer sk_live_xxx
X-API-VersionPassthrough2024-01
X-Client-IDPassthroughportkey-mcp-gateway
x-request-idForwardedFrom agent request
x-correlation-idForwardedFrom agent request
x-tenant-idForwardedFrom agent request
X-User-ClaimsIdentityJSON with user claims

​
When to Use Shared Credentials

Shared credentials make sense when:
  • The MCP server provides shared resources (knowledge bases, analytics)
  • All users should see the same data
  • You don’t need per-user attribution at the MCP server level
  • The external service doesn’t support per-user OAuth
Shared credentials don’t make sense when:
  • Users access personal data (email, messages, private repos)
  • Actions need attribution to individual users
  • The MCP server enforces per-user permissions
For per-user access, use OAuth Auto. Each user authorizes their own access, and Portkey manages tokens per user.

​
Security Considerations

​
Credential Storage

Headers configured in the MCP Registry are stored encrypted. They’re never exposed to agents or included in logs.

​
Credential Isolation

Agent knows:      Portkey API key only
Portkey knows:    MCP server auth headers
MCP Server knows: Its own credentials
Agents never see the MCP server’s authentication credentials. If an agent’s Portkey API key is compromised, the attacker still can’t access the raw MCP server credentials.

​
Rotation

To rotate MCP server credentials:
  1. Generate new credentials with the MCP server
  2. Update the headers in Portkey’s MCP Registry
  3. Old credentials can be revoked immediately
No agent configuration changes required.
TopicDescription
Forwarding HeadersPass headers from agents to MCP servers
Identity ForwardingPass user identity to MCP servers
Authentication OverviewUnderstanding gateway authentication