How to forward Authorization headers through IBM MCP Context Forge to upstream MCP servers?

[elvus]

I need to forward/pass through incoming Authorization headers from the virtual gateway directly to the downstream/original MCP target server.

Right now, the gateway strips or does not relay the Authorization header to the backend service.

Here is my current docker-compose.yml:

services:
  mcp-context-forge:
    image: ghcr.io/ibm/mcp-context-forge:latest
    ports:
      - "4444:4444"
    environment:
      - MCPGATEWAY_UI_ENABLED=true
      - MCPGATEWAY_ADMIN_API_ENABLED=true
      - HOST=0.0.0.0
      - JWT_SECRET_KEY="1PlnAWCYzkFwQI7gHkkVouh26vgajOMb"
      - AUTH_ENCRYPTION_SECRET="super_auth_encryption_key"
      - AUTH_REQUIRED=false
      - MCP_REQUIRE_AUTH=false
      - PLATFORM_ADMIN_EMAIL=admin@example.com
      - PLATFORM_ADMIN_PASSWORD=password
      - PLATFORM_ADMIN_FULL_NAME="Platform Administrator"
      - DATABASE_URL=sqlite:///./mcp.db
      - SECURE_COOKIES=false
      - PLUGINS_ENABLED=true
      - REDIS_URL=redis://redis:6379
    volumes:
      - ./plugins/config.yaml:/app/plugins/config.yaml
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:latest
    container_name: redis
    ports:
      - "6379:6379"
    restart: unless-stopped
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s

[maciejstepniak]

To use the general header pass-through, set the global flag on the gateway: ENABLE_HEADER_PASSTHROUGH=true (and add the header name to the server's passthrough_headers).

The Authorization header itself is used by the gateway's own auth, so it is not forwarded. Instead, send the credential in X-Upstream-Authorization- the gateway renames it to Authorization when forwarding to the upstream. This one works regardless of the flag above.

You may also be interested in ENABLE_OVERWRITE_BASE_HEADERS=true, which lets the client header override a static auth_headers configured on the server.

[elvus]

@maciejstepniak thanks for answering. I make the changes that you propose and it doesn't work:

services:
  mcp-context-forge:
    image: ghcr.io/ibm/mcp-context-forge:latest
    ports:
      - "4444:4444"
    environment:
      - MCPGATEWAY_UI_ENABLED=true
      - MCPGATEWAY_ADMIN_API_ENABLED=true
      - HOST=0.0.0.0
      - JWT_SECRET_KEY="1PlnAWCYzkFwQI7gHkkVouh26vgajOMb"
      - AUTH_ENCRYPTION_SECRET="super_auth_encryption_key"
      - AUTH_REQUIRED=false
      - MCP_REQUIRE_AUTH=false
      - PLATFORM_ADMIN_EMAIL=admin@example.com
      - PLATFORM_ADMIN_PASSWORD=password
      - PLATFORM_ADMIN_FULL_NAME="Platform Administrator"
      - DATABASE_URL=sqlite:///./mcp.db
      - SECURE_COOKIES=false
      - PLUGINS_ENABLED=true
      - REDIS_URL=redis://redis:6379
      - ENABLE_HEADER_PASSTHROUGH=true
      - ENABLE_OVERWRITE_BASE_HEADERS=true

I've already add the Passthrough Headers from the ui

Sending auth header:

Without auth header:

[muhammadbalawal]

The flag you are missing is probably ENABLE_SENSITIVE_HEADER_PASSTHROUGH. Authorization is classified as a sensitive header, so ENABLE_HEADER_PASSTHROUGH=true on its own does not cover it. Both have to be set. From mcpgateway/config.py:

enable_sensitive_header_passthrough: bool = Field(
    default=False,
    description="Enable passthrough of sensitive headers (Authorization, X-API-Key, etc.) when explicitly whitelisted. "
    "Requires enable_header_passthrough=true. Default: false for security. "
    "When enabled, whitelisted sensitive headers bypass router-level filtering.",
)

So in your compose environment you want both:

ENABLE_HEADER_PASSTHROUGH=true
ENABLE_SENSITIVE_HEADER_PASSTHROUGH=true

The second thing worth checking is PASSTHROUGH_HEADERS_SOURCE. It defaults to db, which means a value stored in the database wins and your environment variable is only a fallback:

passthrough_headers_source: Literal["env", "db", "merge"] = Field(
    default="db",
    description="Source priority for passthrough headers: env (environment always wins), db (database wins, default), merge (combine both)",
)

Since you also configured passthrough headers through the admin UI, that stored value is what is being used and your compose setting is ignored. Set PASSTHROUGH_HEADERS_SOURCE=env if you want the compose file to win, or merge if you want both.

Third, and this one overrides everything above: if the target gateway has auth_type of basic or bearer, Authorization passthrough is skipped regardless of the flags. From mcpgateway/utils/passthrough_headers.py:

if gateway.auth_type == "basic" and header_lower == "authorization":
    logger.warning(f"Skipping Authorization header passthrough due to basic auth configuration on gateway {gateway.name}")
    continue
if gateway.auth_type == "bearer" and header_lower == "authorization":
    logger.warning(f"Skipping Authorization header passthrough due to bearer auth configuration on gateway {gateway.name}")
    continue

Client Authorization only passes through when the gateway auth_type is none. Since you registered the target through the UI, check whether it picked up basic or bearer credentials there.

The fastest way to tell which branch you are hitting is the log output. Run with debug logging and look for one of these:

Skipping Authorization header passthrough due to <basic|bearer> auth configuration on gateway <name>
Skipping Authorization header passthrough as it conflicts with pre-defined headers
Passing through client Authorization header (auth_type=none)
Renamed X-Upstream-Authorization to Authorization for upstream passthrough

The second means a collision with a base header, which is what ENABLE_OVERWRITE_BASE_HEADERS=true is for. The last two mean it is working.

If you just want it running without changing the target auth config, X-Upstream-Authorization is the escape hatch. It is handled before all the checks above and gets renamed to Authorization on the way out, so it works even when the gateway has its own auth configured.

I am reading main, so double check the sensitive flag exists in the image tag you are pulling. If you are on an older release that predates it, the auth_type conflict is the more likely cause.

[elvus]

Hi @muhammadbalawal, thanks for the reply! Sending the X-Upstream-Authorization header worked for me.
With header:

Without header: