Hermes MCP Bridge

Read-only MCP bridge exposing Hermes gateway tools to ChatGPT via HTTP/SSE.

Endpoints

• /mcp — StreamableHTTP (primary, MCP spec standard)

• /sse — Server-Sent Events (fallback for legacy clients)

• /health — Health check (no auth)

Read-Only Tools Exposed

Blocked (never exposed):

• messages_send

• permissions_respond

• Any write/execute/create/delete tools

Local Development

# Install deps
pip install -r requirements.txt

# Run (requires Hermes gateway at http://127.0.0.1:8642)
PORT=8080 uvicorn app:app --host 0.0.0.0 --port 8080

# Or with custom Hermes URL
HERMES_GATEWAY_URL=http://localhost:8640 PORT=8080 uvicorn app:app --host 0.0.0.0

Environment Variables

Zeabur Deployment

1. Push this repo to Git

2. In Zeabur dashboard: Add Service → Git Repository

3. Select this repo

4. Important: Disable "Public" toggle (private service)

5. Zeabur auto-detects Python, runs uvicorn app:app --host 0.0.0.0 --port $PORT

6. Service gets internal DNS: http://hermes-mcp-bridge:8080

Phase 2 Network Note

On Zeabur, each service is a separate container. The bridge cannot reach Hermes at 127.0.0.1:8642.

Required for Phase 2: Expose Hermes gateway as an internal Zeabur Service (no public toggle) on port 8642, then set:

HERMES_GATEWAY_URL=http://hermes-gateway:8642

in the bridge service environment.

Auth

If MCP_BRIDGE_TOKEN is set, all /mcp and /sse requests require:

Authorization: Bearer <MCP_BRIDGE_TOKEN>

ChatGPT MCP config example:

{
  "mcpServers": {
    "hermes": {
      "url": "https://hermes-mcp-bridge.zeabur.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

License

Internal tool — not for public distribution.