Forwarding Headers

Pass headers from agent requests to MCP servers.

Header forwarding passes specific headers from agent requests through to MCP servers. Use for distributed tracing, tenant context, or custom metadata that needs to reach the upstream server.

You can also rename headers inline using object entries, so client-side header names can differ from what the upstream server expects.

When to Use

Your agent includes headers with context that the MCP server needs. Maybe a trace ID for distributed tracing. Maybe a tenant ID for multi-tenant servers. Maybe custom metadata your server expects.

Without header forwarding, these headers stop at Portkey. With it, they pass through to the MCP server.

Common scenarios:

• Distributed tracing. Forward x-request-id, x-trace-id, x-correlation-id to correlate logs across services.
• Multi-tenancy. Forward x-tenant-id, x-org-id for tenant-scoped operations.
• User context. Forward x-user-id, x-user-role for upstream authorization.
• Custom metadata. Forward application-specific headers your MCP server expects.

---

Configuration

Configure forward_headers when adding or editing an MCP server in the MCP Registry.

Shorthand (string array)

Forward only the headers you specify. No renaming support in this form:

{
  "forward_headers": ["x-request-id", "x-trace-id", "x-tenant-id"]
}

Other headers from the agent request are dropped.

Allowlist mode

The same behavior with explicit configuration. Entries in the headers array can be:

• A string — forwards the header as-is.
• An object { "from": "<client_header>", "to": "<upstream_header>" } — forwards the header with its name changed.

{
  "forward_headers": {
    "mode": "allowlist",
    "headers": [
      "x-trace-id",
      { "from": "x-tenant-id", "to": "X-Organization-Id" },
      { "from": "x-env", "to": "X-Deploy-Environment" }
    ]
  }
}

In this example, x-trace-id is forwarded as-is, x-tenant-id arrives at the upstream as X-Organization-Id, and x-env arrives as X-Deploy-Environment.

All-except mode

Forward everything except headers you exclude. String entries are excluded; object entries rename forwarded headers:

{
  "forward_headers": {
    "mode": "all-except",
    "headers": [
      "host",
      "connection",
      { "from": "x-tenant-id", "to": "X-Org-Id" }
    ]
  }
}

Here, host and connection are excluded. All other headers are forwarded. Additionally, x-tenant-id is renamed to X-Org-Id before reaching the upstream server.

Use all-except mode carefully. It forwards more headers than you might expect, which could leak information or cause conflicts. Prefer explicit allowlists when possible.

---

Security

Protected Headers

These headers are never forwarded regardless of your configuration:

Header	Reason
cookie	Session data should not leak
set-cookie	Response header, not request
x-api-key	Could leak API keys
x-portkey-api-key	Portkey authentication
api-key	Could leak API keys
apikey	Could leak API keys
x-auth-token	Could leak tokens
x-access-token	Could leak tokens
x-user-claims	Identity spoofing prevention
x-user-jwt	Identity spoofing prevention

In all-except mode, these are automatically added to the blocklist. You cannot override this behavior.

Header mapping validation

When using object entries for header renaming, both the source (from) and target (to) header names are validated against the protected headers blocklist. If either name is protected, the mapping is rejected and the header is not forwarded.

Header matching on the source name is case-insensitive.

// This mapping is rejected — x-api-key is protected
{ "from": "x-api-key", "to": "X-Custom-Key" }

// This mapping is also rejected — the target is protected
{ "from": "x-custom", "to": "x-auth-token" }

Identity Headers Are Protected

If you use Identity Forwarding, identity headers are also protected:

• X-User-Claims
• X-User-JWT

This prevents clients from spoofing user identity by sending fake identity headers.

---

Header Priority

When multiple sources provide headers, they merge in this order (later values override earlier ones):

Priority	Source	Description
1 (lowest)	Forwarded headers	Headers from the agent request
2	Auth headers	headers configured on the MCP server
3	Passthrough headers	passthrough_headers configured on the server
4 (highest)	Identity headers	Headers from Identity Forwarding

Why this order matters:

• Authentication headers configured on the server cannot be overridden by agents
• Static passthrough headers take precedence over agent headers
• Identity headers always win—agents cannot spoof user identity

Example:

Agent sends:        X-Custom: agent-value
Server config:      X-Custom: server-value (in passthrough_headers)

Result: MCP server receives X-Custom: server-value (server config wins).

---

Agent Configuration

Include headers in your MCP client configuration:

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.portkey.ai/linear/mcp",
      "headers": {
        "x-portkey-api-key": "pk_xxx",
        "x-request-id": "req-12345",
        "x-tenant-id": "tenant-abc"
      }
    }
  }
}

Or set headers per request in code:

Python

import uuid

headers = {
    "x-portkey-api-key": "pk_xxx",
    "x-request-id": str(uuid.uuid4()),
    "x-trace-id": current_trace_id,
    "x-tenant-id": "tenant-abc"
}

async with streamablehttp_client(url, headers=headers) as (read, write, _):
    # x-request-id, x-trace-id, and x-tenant-id forwarded to MCP server
    ...

TypeScript

import { randomUUID } from 'crypto';

const headers = {
  "x-portkey-api-key": "pk_xxx",
  "x-request-id": randomUUID(),
  "x-trace-id": currentTraceId,
  "x-tenant-id": "tenant-abc"
};

// Headers forwarded based on forward_headers configuration

---

Example: Distributed Tracing

You want to correlate MCP requests with your application’s traces.

Server configuration:

{
  "forward_headers": ["x-request-id", "x-trace-id", "traceparent"]
}

Agent request:

{
  "headers": {
    "x-portkey-api-key": "pk_xxx",
    "x-request-id": "req-abc123",
    "x-trace-id": "trace-xyz789",
    "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
  }
}

MCP server receives:

x-request-id: req-abc123
x-trace-id: trace-xyz789
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

Now your MCP server logs include the same trace IDs as your application.

---

Example: Multi-Tenant Server

Your internal MCP server needs tenant context to scope data access.

Server configuration:

{
  "forward_headers": ["x-tenant-id", "x-org-id"]
}

Agent request:

{
  "headers": {
    "x-portkey-api-key": "pk_xxx",
    "x-tenant-id": "tenant-acme",
    "x-org-id": "org-12345"
  }
}

MCP server receives:

x-tenant-id: tenant-acme
x-org-id: org-12345

Your server uses these headers to filter data to the correct tenant.

---

Example: Header renaming

Your agent sends x-tenant-id but your upstream MCP server expects X-Organization-Id.

Server configuration:

{
  "forward_headers": {
    "mode": "allowlist",
    "headers": [
      "x-request-id",
      { "from": "x-tenant-id", "to": "X-Organization-Id" }
    ]
  }
}

Agent request:

{
  "headers": {
    "x-portkey-api-key": "pk_xxx",
    "x-request-id": "req-abc123",
    "x-tenant-id": "tenant-acme"
  }
}

MCP server receives:

x-request-id: req-abc123
X-Organization-Id: tenant-acme

The x-tenant-id header is renamed to X-Organization-Id before reaching the upstream server.

---

Combining with Identity Forwarding

Header forwarding and identity forwarding serve different purposes:

Feature	Purpose	Source
Header Forwarding	Pass metadata (traces, tenants)	Agent request
Identity Forwarding	Pass authenticated user claims	Portkey (from validated token)

Use both together:

{
  "forward_headers": ["x-request-id", "x-trace-id"],
  "user_identity_forwarding": {
    "method": "claims_header",
    "include_claims": ["sub", "email", "workspace_id"]
  }
}

The MCP server receives:

• x-request-id and x-trace-id from the agent (for tracing)
• X-User-Claims from Portkey (for user identity)

---

Related

Topic	Description
Identity Forwarding	Pass authenticated user claims to MCP servers
Custom Auth	Configure static headers for MCP servers