AGENT SKILL

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://.../mcp endpoint.
  • Often the repo is DOCS-ONLY + a server.json manifest with a remotes[].url — clone it for reference, but there is nothing to build or install locally.

Workflow

  1. Identify server type first. server.json with remotes[].url ⇒ remote server: no build step. Keep the clone for its tools.md/editing.md docs.
  2. 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"}}}'
    
  3. Add the server — MUST run in a PTY. Non-interactive runs fail with non-interactive environment and no cached tokens found and 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)
  4. 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.
  5. 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.
  6. Verify:
    • hermes mcp list shows the server; config.yaml has mcp_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

  1. 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 to 127.0.0.1:<port>/callback dies, 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.
  2. Recovering a burned callback: re-run hermes mcp add <name> --url <url> --auth oauth in 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.
  3. 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, then process(action='submit', data=<url>) into the waiting PTY. Confirm state= matches the URL the CLI printed before exchanging.
  4. The paste prompt rejects non-callback input (Pasted input did not contain code= or error= — ignoring.). Answer any earlier prompt ([y/N]) with submit BEFORE the paste prompt appears, or type skip to bail. Submitting stray text to the paste prompt does nothing useful and loops.
  5. Access tokens are short-lived (~1h) with refresh-token rotation. If a connection dies later, hermes mcp reauth <name> (or hermes mcp login <name>) re-runs the flow.
  6. 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.
  7. 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