hermes-agent-mcp-bridge

Expose a local Hermes agent over remote MCP with OAuth 2.1 public-client auth (DCR, CIMD, PKCE).

Why

Official Hermes mcp-serve is local stdio only (hermes mcp-serve). This bridge exposes Hermes over remote MCP: streamable HTTP at {issuer}/mcp, with standards OAuth 2.1 public-client auth. There is no client secret. Clients register with Dynamic Client Registration or a Client ID Metadata Document, and the authorization-code flow uses PKCE S256. ChatGPT, Cursor, and other MCP clients can connect. The agent, its tools, and its credentials stay on loopback.

The remote client queues a prompt and reads the reply (ask_hermes, get_job, bridge_status). It does not receive the agent's own tools.

Related MCP server: CommandCore

Architecture

flowchart LR
  client[Remote MCP client]
  proxy[HTTPS reverse proxy]
  bridge[Bridge on 127.0.0.1:8765]
  store[(SQLite and signing key)]
  hermes[Hermes API on 127.0.0.1:8642]
  client -->|OAuth and POST /mcp| proxy --> bridge
  bridge --> store
  bridge -->|POST /v1/runs| hermes

The public listener serves discovery, POST /oauth/register, POST /oauth/token, GET /oauth/jwks, and POST /mcp. With the default consent.exposure: public, the approval page is GET /oauth/authorize on that same origin. consent.exposure: tailnet serves approval only on consent.bind_port. See docs/SETUP.md and docs/SECURITY.md.

Quickstart: connect ChatGPT in 5 minutes

ChatGPT is expected to work with a developer-mode custom MCP connector. A live ChatGPT session is not part of this repository's tests. The checklist is in docs/CLIENTS.md. Use a separate data directory, port, and issuer for a first test.

You need Python 3.11 or newer, a Hermes Agent 0.21.x API server on 127.0.0.1:8642, and an HTTPS name that forwards to the bridge. Docker and a longer Tailscale walkthrough are in docs/SETUP.md.

1. On the Hermes host, enable the API server (Hermes 0.21 uses ~/.hermes/.env for these two variables) and start the gateway:

   API_SERVER_ENABLED=true
   API_SERVER_KEY=replace-with-a-long-random-string

   hermes gateway

2. Install the bridge, point server.issuer and server.resource at that public origin, and start it. resource is the MCP URL. It defaults to issuer + /mcp. Neither value may have a trailing slash. Leave consent.exposure: public (the example default) so the approval page is on the issuer origin.

   python -m venv .venv
   .venv/bin/pip install -e .
   cp config.example.yaml config.yaml
   # edit server.issuer and server.resource
   mkdir -p secrets
   umask 077
   printf '%s\n' 'replace-with-a-long-random-string' > secrets/hermes_api_key
   chmod 0600 secrets/hermes_api_key
   .venv/bin/hermes-agent-mcp-bridge init --config config.yaml
   .venv/bin/hermes-agent-mcp-bridge serve --config config.yaml

   init prints the owner password once. Store it in a password manager. serve binds 127.0.0.1:8765 and does not print the password.

3. Publish that loopback port over HTTPS. With Tailscale, confirm the flags on your client (tailscale funnel --help), then:

   tailscale funnel --bg 8765

   Set server.issuer to the HTTPS origin that command shows, with no path and no trailing slash, and set server.resource to that origin plus /mcp. Do not publish the Hermes port 8642.

4. Check discovery from the bridge machine:

   curl -sS http://127.0.0.1:8765/healthz
   curl -sS http://127.0.0.1:8765/.well-known/oauth-protected-resource
   curl -sS http://127.0.0.1:8765/.well-known/oauth-authorization-server

   The authorization-server document includes code_challenge_methods_supported: ["S256"], registration_endpoint, client_id_metadata_document_supported: true, token_endpoint_auth_methods_supported: ["none"], and authorization_response_iss_parameter_supported: true.

5. In ChatGPT, enable developer mode and add a custom MCP connector. Paste the resource URL (https://bridge.example.com/mcp with your host). Do not paste a bearer token. You do not create a client id. CIMD and DCR are both advertised. When the approval page opens, deny the request if the redirect host is not chatgpt.com. Otherwise enter the owner password from init.

6. Call bridge_status, then ask_hermes with a short prompt, then get_job with the returned job id.

ChatGPT's stable redirect, when the server sends RFC 9207 iss on every redirect, is https://chatgpt.com/connector_platform_oauth_redirect, with the CIMD document https://chatgpt.com/oauth/client.json. Both that form and the per-connection https://chatgpt.com/connector/oauth/{callback_id} form are accepted. This server does not verify private_key_jwt client assertions. The public-client method is none.

Connect Cursor

Cursor is expected to work through Dynamic Client Registration. A live Cursor session is not part of this repository's tests.

1. Use the same bridge as above. Leave redirects.private_schemes at the example default, cursor. A private-use URI is accepted when its authority contains a dot, which covers cursor://anysphere.cursor-mcp/oauth/callback. Set redirects.private_schemes to [] to refuse that scheme. HTTPS and loopback redirects still register.

2. Add a remote MCP server whose URL is server.resource. Cursor's user mcp.json, or a project .cursor/mcp.json, is:

   {
     "mcpServers": {
       "hermes-agent": {
         "url": "https://bridge.example.com/mcp"
       }
     }
   }

   Omit headers and omit auth. This bridge does not accept a static bearer on POST /mcp, and it rejects a client secret at POST /oauth/register. Cursor registers itself. There is no client id to paste.

3. Registration may list cursor://anysphere.cursor-mcp/oauth/callback, https://www.cursor.com/agents/mcp/oauth/callback, and a loopback URI such as http://localhost:8787/callback. Unusable URIs are dropped. The rest are kept. Loopback HTTP ignores the port and treats localhost, 127.0.0.1, and [::1] as the same host.

4. Approve /oauth/authorize with the owner password after you read the client name and the redirect URI. The only scope this server advertises is hermes:ask.

5. Call bridge_status, then ask_hermes, then get_job.

Tools

Access tokens are short-lived RS256 JWTs. Refresh tokens rotate in SQLite. The signing key is created on first run at data/signing-key.pem with mode 0600.

Clients

How this differs from similar projects

Those projects solve the same shape of problem. Read their READMEs for their current behavior. The rows above describe the public documentation as of November 2026.

Documentation

• docs/SETUP.md — install, Hermes API, Tailscale, connect, verify

• docs/CLIENTS.md — Grok Bot, ChatGPT, Claude, Cursor, and the ChatGPT test checklist

• docs/CONFIGURATION.md — config file and environment variables

• docs/SECURITY.md — threat model, allowlist, consent, keys, private vulnerability reports

• docs/TROUBLESHOOTING.md — invalid_request, redirect mismatch, stale client id

• docs/RELEASE_NOTES_v0.1.0.md

• CONTRIBUTING.md

• CHANGELOG.md

Help

• Bugs and feature requests: Issues

• Questions and setup help: Discussions

• Security vulnerabilities: report privately. Do not open a public issue.

Tests

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check hermes_agent_mcp_bridge tests
.venv/bin/pytest -q

The tests use an in-memory Hermes double. They do not contact a live agent or a live chat client. CI is .github/workflows/ci.yml (Python 3.12, ruff, pytest, gitleaks).

License

MIT. See LICENSE. The Python dependencies used here (cryptography, httpx, PyJWT, pydantic, PyYAML, python-multipart, starlette, uvicorn) are MIT, BSD, or Apache-2.0. Nothing in this tree is vendored from another project.

Trademarks

Grok, Grok Bot, ChatGPT, OpenAI, Claude, Anthropic, Cursor, Tailscale, Hermes, and Nous are trademarks of their respective owners. This project is not affiliated with, endorsed by, or sponsored by those owners.