From 261b0f82409391fb64ed247df6f62b38c3d335ec Mon Sep 17 00:00:00 2001 From: teknium1 <127238744+teknium1@users.noreply.github.com> Date: Thu, 16 Jul 2026 04:51:03 -0700 Subject: [PATCH] docs(mcp): document redirect_uri proxied callbacks + redirect_host WAF workaround Adds the proxied-callback option to the remote/headless OAuth section, links the mcp-oauth-remote-gateway skill for fully headless gateways, and documents the WAF pitfall behind redirect_host. --- website/docs/user-guide/features/mcp.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md index bf946fde10ec..f025aea1f450 100644 --- a/website/docs/user-guide/features/mcp.md +++ b/website/docs/user-guide/features/mcp.md @@ -226,6 +226,21 @@ On first connect, Hermes prints an authorize URL, opens your browser when possib - **Paste-back (no setup):** on an interactive terminal Hermes prints "Or paste the redirect URL here…" alongside the authorize URL. Open the URL in your browser, approve, copy the full URL the browser ends up on (the redirect will show a connection error — that's expected), paste it at the prompt. Bare `?code=…&state=…` query strings work too. - **SSH port forward:** `ssh -N -L :127.0.0.1: user@host` in a separate terminal, then let the redirect flow normally. +- **Proxied callback (`redirect_uri`):** when a public HTTPS endpoint forwards to the host (e.g. a Tailscale Funnel or reverse proxy pointed at the callback port), set `oauth.redirect_uri` and the browser redirect reaches Hermes on its own — no tunnel or paste needed: + +```yaml +mcp_servers: + myserver: + url: "https://mcp.example.com/mcp" + auth: oauth + oauth: + redirect_port: 8765 # fixed port for the proxy to target + redirect_uri: "https://oauth.example.ts.net/callback" +``` + +For fully headless gateways (messaging bot, no interactive terminal at all), the optional [`mcp-oauth-remote-gateway` skill](../skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md) walks the agent through completing the flow manually and writing tokens where Hermes expects them. + +**Pitfall — WAF rejects `127.0.0.1` redirect URIs.** A few providers front their authorization server with a WAF that 403s any authorize request whose query string contains a literal `127.0.0.1` (Reclaim.ai's AWS API Gateway is a known example — every attempt returns `{"message":"Forbidden"}` before reaching the OAuth app). Set `oauth.redirect_host: localhost` to use `http://localhost:/callback` instead; the callback listener still binds `127.0.0.1` either way. See [OAuth over SSH / Remote Hosts](../../guides/oauth-over-ssh.md#mcp-servers) for the full walkthrough, including DCR-less servers (e.g. Slack), pre-registered `client_id`/`client_secret`, scope customization, and re-auth via `hermes mcp login `.