remote-mcp-oauth-setup
Use when adding OAuth-gated remote MCP servers to Hermes.
- License 许可
- MIT
- 最近更新
- 2026-08-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- remote-mcp-oauth-setup
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "hermes", "mcp", "oauth", "remote-server", "setup", "configuration" ], "related_skills": [ "hermes-agent" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Use when adding OAuth-gated remote MCP servers to Hermes.
03 SKILL.md 正文
Remote MCP Server Setup (OAuth)
Connecting Hermes to REMOTE (Streamable HTTP) MCP servers gated behind OAuth 2.1 — e.g.
SVGator (https://mcp.svgator.com/mcp, 22 tools), Linear, Betterstack, or any
https://.../mcp endpoint using dynamic client registration + PKCE.
Load the hermes-agent skill's references/native-mcp.md for the config schema; THIS skill
covers the operational flow and the failure modes that doc doesn't.
Trigger
- User asks to "set up / connect / clone-and-configure" an MCP server whose repo or docs
point at a remote
https://.../mcpendpoint. - Often the repo is DOCS-ONLY + a
server.jsonmanifest with aremotes[].url— clone it for reference, but there is nothing to build or install locally.
Workflow
- Identify server type first.
server.jsonwithremotes[].url⇒ remote server: no build step. Keep the clone for its tools.md/editing.md docs. - Health-check before auth (server reachable; unauthenticated 401 is EXPECTED):
curl -s https://HOST/.well-known/oauth-authorization-server # endpoints, S256 support curl -s -o /dev/null -w "%{http_code}\n" -X POST https://HOST/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' - Add the server — MUST run in a PTY. Non-interactive runs fail with
non-interactive environment and no cached tokens foundand the config is NOT saved (the "Save config anyway?" prompt defaults to no). Use:terminal(command="hermes mcp add <name> --url <url> --auth oauth", background=true, pty=true) - The flow: CLI does dynamic client registration (PKCE S256), prints an authorize URL,
auto-opens the browser, and blocks at a paste prompt:
Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter. - User authorizes in their REAL browser (see pitfall 1). The redirect must reach the
CLI's localhost callback (
127.0.0.1:<port>/callback); the CLI exchanges the code for tokens, lists tools, asks enable-all, and saves config. - Verify:
hermes mcp listshows the server;config.yamlhasmcp_servers.<name> {url, auth: oauth}- Token file exists:
~/.hermes/mcp-tokens/<name>.json(0600) alongside<name>.client.json(client registration) and<name>.meta.json(server metadata) hermes mcp test <name>connects and lists tools
Pitfalls
- NEVER open the OAuth authorize URL in the Hermes preview pane (
open_preview). The preview pane is a rendering surface, not a browser session with a route back to the CLI's localhost listener: it consumes the one-time authorization code, the redirect to127.0.0.1:<port>/callbackdies, the CLI prints✗ Failed to connect:with an EMPTY error, and the code is burned. Let the CLI's auto-opened real browser complete the flow. - Recovering a burned callback: re-run
hermes mcp add <name> --url <url> --auth oauthin a fresh PTY — the client registration (mcp-tokens/<name>.client.json) persists and is reused. Have the user authorize in the real browser this time. - Manual paste completion (browser can't reach localhost, e.g. sandboxed): ask the user
to copy the full
http://127.0.0.1:<port>/callback?code=...&state=...from the address bar, thenprocess(action='submit', data=<url>)into the waiting PTY. Confirmstate=matches the URL the CLI printed before exchanging. - The paste prompt rejects non-callback input (
Pasted input did not contain code= or error= — ignoring.). Answer any earlier prompt ([y/N]) withsubmitBEFORE the paste prompt appears, or typeskipto bail. Submitting stray text to the paste prompt does nothing useful and loops. - Access tokens are short-lived (~1h) with refresh-token rotation. If a connection
dies later,
hermes mcp reauth <name>(orhermes mcp login <name>) re-runs the flow. - Diagnosis script shipped in the Hermes source classifies connection state without
printing secrets:
~/.hermes/hermes-agent/optional-skills/mcp/mcp-oauth-remote-gateway/scripts/diagnose-oauth-mcp.py <name>→ branches TOKEN_OK / REFRESH_FIXED / SESSION_REVOKED / REFRESH_DEAD. - Provider holds tokens server-side; the model only ever sees tool results. Never log or
paste access tokens. Hermes env-filters stdio subprocesses, so secrets must be passed via
the
env:config key.
04 同仓库更多 Skills
web-ui-verification
Verify web UIs via headless Chrome CDP, no vision needed.
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
spike
Throwaway experiments to validate an idea before build.
simplify-code
Parallel 4-agent cleanup of recent code changes.
scroll-driven-3d-websites
Scroll-scrubbed 3D promo sites (Three.js + GSAP).