MCP OAuth Remote Gateway - Setup Guide¶

Source: nousresearch/hermes-agent Repo: 229K⭐ · Skill installs: 1 · First Seen: ~August 4, 2026 Category: MCP / Authentication / Infrastructure Security: Gen Agent Trust Hub Pass · Socket Pass · Snyk Pass

The official Hermes Agent skill for the most common MCP OAuth failure mode in production deployments. 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 redirect_uri. That works on a local CLI. It breaks completely on a remote gateway (container, VPS, messaging bot), because the user's browser resolves 127.0.0.1 to their own laptop - the authorization code never reaches Hermes.

This skill performs 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:

Hermes runs as a remote gateway - container, VPS, or bot deployment, not a local CLI
You need to connect an MCP server that requires OAuth 2.0 authorization (Google, GitHub, Slack, etc.)
The built-in browser flow fails because the loopback redirect never reaches the Hermes process
You can run the authorization code exchange manually and place tokens in Hermes' token storage

Installation¶

# Via skills.sh
npx skills add https://github.com/nousresearch/hermes-agent --skill mcp-oauth-remote-gateway

# Direct from the Hermes Agent repo
git clone --depth 1 https://github.com/nousresearch/hermes-agent.git /tmp/hermes-agent
cp -r /tmp/hermes-agent/skills/infrastructure/mcp-oauth-remote-gateway ~/.hermes/skills/

How It Works¶

The skill performs the OAuth authorization-code flow manually - outside the Hermes process
The redirect URI is registered as a public/remote endpoint (or handled via manual code paste)
The exchanged tokens are written into the exact files Hermes' token storage reads
/reload-mcp is issued; Hermes finds cached tokens and skips the browser flow

The result is identical to a successful local OAuth, but the token files are populated out-of-band.

Prerequisites¶

Requirement	Details
Remote Hermes gateway	Container, VPS, or messaging-bot deployment
OAuth client credentials	Client ID/secret from the MCP server's provider console
Redirect URI control	Ability to register a non-loopback redirect URI, or capture the callback code manually
Hermes token storage access	Filesystem access to the Hermes profile directory

CorpusIQ Use Cases¶

Use Case	How
Remote gateway OAuth	Connect OAuth MCP servers when Hermes runs on the DGX Spark or Mac Mini behind a gateway
Bot deployments	Authorize MCP servers for Telegram-bot-driven Hermes instances
Token seeding	Pre-seed tokens in images before first boot, skipping interactive auth entirely
Recovery flows	Re-authorize a server whose refresh token expired without a browser session

Integration with CorpusIQ¶

CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.

This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.

See what CorpusIQ connects

Limitations / Verification¶

Manual flow requires comfort with OAuth 2.0 authorization-code mechanics
Skill is brand new (first seen early August 2026) - pin the install and re-check on Hermes upgrades
Verify: after placing tokens and running /reload-mcp, confirm the MCP server shows as connected with hermes mcp list or the in-session MCP status view

Powered by CorpusIQ