mcp-oauth-remote-gateway

Do the OAuth flow manually: discover the server's metadata via RFC 9728, register a dynamic client with a 127.0.0.1 redirect URI, build a PKCE authorize URL, have the user paste back the failed callback URL, then exchange the code and write tokens into $HERMES_HOME/mcp-tokens/.

The built-in OAuth client registers http://127.0.0.1:<port>/callback as the redirect URI and listens inside the Hermes process. On a remote gateway, the user's browser resolves 127.0.0.1 to their own laptop, so the authorization code never reaches Hermes.

No. GitHub does not expose RFC 7591 DCR, so you must use a Personal Access Token or a pre-registered OAuth App with a client_secret. Servers accepting static Bearer tokens should use headers.Authorization instead of OAuth.

Hermes keeps a module-level circuit breaker that can survive a reload and short-circuit calls before reaching the server. Run scripts/diagnose-oauth-mcp.py first; it smoke-tests the stored token and tells you whether to restart, refresh, or fully re-authenticate.

An invalid_grant response means the refresh token is dead server-side and cannot be recovered from the gateway. The only fixes are a full interactive re-authorization flow or switching to a static API key, which is more durable for unattended gateways.

Prefer a static key whenever the provider offers one and the gateway is unattended. Providers like Stripe revoke OAuth sessions roughly weekly, and a restricted key has no session, refresh, or expiry cycle to maintain.