Agent skill · software engineering · nousresearch
mcp-oauth-remote-gateway
Manual OAuth for remote MCP servers on headless gateways.
Why this skill is useful
Adds manual OAuth handling for remote MCP servers, including token storage integration that the AI wouldn't generate on its own.
What it needs
Requires hermes installed locally. About 11k tokens when loaded. Last updated 2026-08-07. 226,679 stars on the source repository.
What this skill does
MCP OAuth on a Remote Hermes Gateway Overview Hermes' built-in MCP OAuth client runs a one-shot HTTP listener on 127.0.0.1:<port> inside the Hermes process and registers that loopback address as the OAuth redirecturi. That works perfectly for a local CLI on the user's own machine. It breaks completely when Hermes runs as a remote gateway (container, VPS, messaging bot), because the user's browser resolves 127.0.0.1 to the user's own laptop, not the remote container — so the authorization code never reaches Hermes. This skill does the OAuth dance by hand and writes the resulting tokens into the exact files Hermes' token storage expects, so a subsequent /reload-mcp finds cached tokens and skips the browser flow entirely. When to Use Use this skill when all of the following are true: 1. The user wants to add a remote HTTP MCP server that requires OAuth (not a static Bearer token). 2. Hermes is running as a remote gateway (container, VPS, Docker, managed service) — NOT a local CLI on the user's laptop. 3. The server supports OAuth 2.1 with PKCE and RFC 7591 Dynamic Client Registration (most modern MCP servers do — Better Stack, Linear, Cloudflare, Datadog, etc.). If it doesn't support DCR (GitHub is the notable exception), this skill does not apply — use a pre-registered OAuth App or a Personal Access Token instead. Do NOT use this for: Local CLI Hermes — just set auth: oauth in mcpservers.<name> and /reload-mcp. The built-in flow opens a browser and captures the callback on localhost. Works perfectly. Servers that accept a static Bearer token (API key) — always prefer headers.Authorization: "Bearer <token>" when the user is willing. Simpler, no refresh dance. GitHub Copilot MCP (api.githubcopilot.com/mcp/) — GitHub does not expose DCR. Use a PAT or a pre-registered OAuth App (see pitfall 12). Why the Built-in OAuth Flow Fails on a Remote Gateway Hermes' native MCP OAuth client (tools/mcpoauth.py): 1. Picks a free local port P. 2. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills nousresearch/mcp-oauth-remote-gateway