Behind a proxy¶

This is the page to read before setting GANGWAY_CLIENT_IP_HEADER. Getting it wrong does not produce an error — the server starts, answers requests, and appears to filter by origin. It just is not actually checking who is calling.

Which header to read¶

Adding a proxy later invalidates this choice. With x-real-ip behind a chain, the header carries the address of the last proxy, not the caller — because each proxy in the chain overwrites it with what it saw immediately in front of it. And an allowlist that matches every caller coming through that last proxy is no allowlist at all: it now says yes to anyone who can reach that proxy, which after adding a second hop is no longer just your known caller.

The same applies in reverse: removing a proxy, or moving from a single reverse proxy to a chain (a CDN in front of a load balancer, say), is a configuration change on this side too, not just on the proxy's.

How the peer decides whether a header is trusted at all¶

GANGWAY_TRUSTED_PROXIES is checked first, unconditionally: the connection that reached Gangway is only ever trusted to have written an honest forwarding header if its own address falls inside that list. A request from outside GANGWAY_TRUSTED_PROXIES has every header it presents ignored, and only its own TCP peer address is used — so a caller cannot forge X-Forwarded-For to impersonate an address the allowlist accepts. This is why an empty GANGWAY_TRUSTED_PROXIES correctly disables header parsing altogether: nothing is trusted, so nothing is read.

Traefik¶

services:
  gangway:
    # ...
    environment:
      GANGWAY_CLIENT_IP_HEADER: x-forwarded-for
      GANGWAY_TRUSTED_PROXIES: 172.16.0.0/12  # Traefik's Docker network

Traefik sets X-Forwarded-For by default. If Gangway and Traefik share a Docker network, GANGWAY_TRUSTED_PROXIES needs to cover that network's subnet — not 127.0.0.1/32, since the connection arrives from Traefik's container address, not localhost.

Caddy¶

Caddy's reverse_proxy also sets X-Forwarded-For by default:

example.com {
    reverse_proxy gangway:8080
}

GANGWAY_CLIENT_IP_HEADER=x-forwarded-for
GANGWAY_TRUSTED_PROXIES=<caddy's address or subnet>

NGINX¶

NGINX does not set X-Forwarded-For on its own — it has to be configured:

location /mcp {
    proxy_pass http://gangway:8080;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
}

With exactly this NGINX instance as the only proxy in front of Gangway, X-Real-IP is the simpler and unambiguous choice:

GANGWAY_CLIENT_IP_HEADER=x-real-ip
GANGWAY_TRUSTED_PROXIES=<nginx's address or subnet>

Pangolin¶

A Pangolin resource forwards through its own Traefik instance; the same x-forwarded-for guidance as above applies, with GANGWAY_TRUSTED_PROXIES covering the network Pangolin's Traefik container reaches Gangway from — typically the shared Docker network the resource's target is attached to, not Pangolin's public-facing address.

Cloudflare¶

Cloudflare sets CF-Connecting-IP to the original client address, regardless of how many internal hops the request took inside Cloudflare's own network — that is the point of the header, and why it is the right choice only when Cloudflare is the outermost proxy:

GANGWAY_CLIENT_IP_HEADER=cf-connecting-ip
GANGWAY_TRUSTED_PROXIES=<Cloudflare's published IP ranges>

Running a streamable-HTTP MCP server behind Cloudflare's proxy (the "orange cloud") works, but three separate settings can each silently break it — none of them related to the header choice above:

None of these three interact with GANGWAY_CLIENT_IP_HEADER or GANGWAY_TRUSTED_PROXIES — they can each break the connection while origin filtering continues to work exactly as configured, which is what makes them easy to misdiagnose as an allowlist problem when they are not one.