forgejo-mcp-broker/docs/deploy-caddy.md

Deploying fjmcp-broker behind Caddy

This is the front-end half of the production deploy. Pair with docs/deploy-podman.md for the broker container itself.

Why Caddy

The broker terminates plain HTTP on 127.0.0.1:8080. Caddy adds:

• automatic Let's Encrypt TLS;
• HTTP→HTTPS redirect;
• SSE-friendly proxying for the /mcp endpoint;
• a clean place to pin rate limits later (issue -ttl).

Other reverse proxies (nginx, Traefik) work too — three knobs to mind:

1. Disable response buffering on /mcp. SSE is useless behind a proxy that buffers the response. In Caddy, flush_interval -1. In nginx, proxy_buffering off.
2. Forward X-Forwarded-Proto for free. The broker doesn't use it for issuer URL construction (intentional — see below), but downstream tooling and access logs benefit.
3. Don't strip /oauth or /.well-known paths. The broker mounts every public endpoint at the root.

The host-header trap

Discovery documents at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource carry the issuer URL — where clients should send Bearer tokens, where they should land for authorization, etc. If these URLs are constructed from the inbound Host header, an attacker can craft a request whose response advertises attacker-controlled endpoints. A naive client follows them and leaks credentials.

The broker defends against this by deriving every URL from FJMCP_BROKER_PUBLIC_URL at startup, ignoring the request's Host entirely. Set that env var to exactly the hostname Caddy serves — mismatch shows up as redirects to the wrong host.

There's an explicit regression test for this attack (TestDiscovery_IssuerIgnoresHostHeader).

Quick start

Assuming the broker is already running per deploy-podman.md:

sudo cp deploy/caddy/Caddyfile /etc/caddy/Caddyfile
sudo $EDITOR /etc/caddy/Caddyfile     # replace mcp.example.com
sudo systemctl reload caddy

Verify:

curl -fsS https://mcp.example.com/healthz | jq .
curl -fsS https://mcp.example.com/.well-known/oauth-authorization-server | jq .issuer
# → "https://mcp.example.com"   (matches FJMCP_BROKER_PUBLIC_URL)

SSE through Caddy

The /mcp endpoint streams Server-Sent Events for tool responses. Default reverse-proxy buffering breaks this — the client sees nothing until the response completes, defeating the whole streaming model. flush_interval -1 in the example Caddyfile tells Caddy to flush every write through to the client immediately.

Quick sanity check (after wiring the OAuth flow end-to-end):

# Use a long-running tool call as the test. Authorization elided.
curl --no-buffer -N \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",...}' \
  https://mcp.example.com/mcp

You should see event: message\ndata: ...\n\n arrive incrementally, not all at once.

Rate limits (optional, recommended)

Caddy doesn't ship with a rate-limit module by default. The caddy-ratelimit plugin adds one:

xcaddy build --with github.com/mholt/caddy-ratelimit

Then in your Caddyfile:

mcp.example.com {
    @oauth_register path /oauth/register
    @oauth_token    path /oauth/token

    rate_limit @oauth_register {
        zone register {
            key {remote_host}
            events 5
            window 1m
        }
    }
    rate_limit @oauth_token {
        zone token {
            key {remote_host}
            events 30
            window 1m
        }
    }

    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1
        # ... rest as above
    }
}

This is tracked as backlog issue -ttl. Skip it for first deployment; add when the audit log shows abuse worth blocking.

Troubleshooting

/.well-known returns the wrong issuer. FJMCP_BROKER_PUBLIC_URL in the broker's env doesn't match the Caddy hostname. Fix it in ~/.config/fjmcp-broker.env and systemctl --user restart fjmcp-broker.

SSE responses arrive only when complete. Buffering is on somewhere in the chain. Check flush_interval -1. If you have another proxy in front of Caddy (a CDN, a load balancer), it may be buffering too — disable response buffering there as well.

Caddy can't reach 127.0.0.1:8080. The Quadlet unit publishes the broker on loopback only. Confirm the container is up (systemctl --user status fjmcp-broker) and that the port is actually published (ss -tlnp | grep 8080).

TLS issues a wrong cert. Caddy needs ports 80 and 443 open. Make sure no other process is bound to them; Caddy listens by default.