Hermes MCP

Hermes MCP is a hosted MCP gateway for messaging, knowledge, and social connectors.

The production endpoint is:

https://hermes.squaremcp.com/mcp

Hermes currently supports MCP access patterns for:

1. email
2. Obsidian vault notes
3. WhatsApp Business
4. LinkedIn
5. Telegram
6. additional social connectors that are in various states of credentialing and rollout

---

What Hermes is for

Hermes is the integration and connector layer behind broader product work such as SquareMCP.

Use Hermes when you want:

1. an MCP endpoint that exposes real tools over Streamable HTTP
2. API-key or OAuth-protected access
3. connector access from agent clients such as Codex CLI, Claude Code, opencode, or ChatGPT

---

Core transports

Transport	URL
Streamable HTTP (preferred)	https://hermes.squaremcp.com/mcp
Legacy SSE	https://hermes.squaremcp.com/sse

---

Authentication

Hermes accepts:

1. x-api-key header
2. ?key= query parameter
3. Authorization: Bearer ... for OAuth-based clients

For local/manual config examples in this repo, always substitute your own value for:

YOUR_MCP_API_KEY

Do not commit live API keys into repo config files.

---

Client setup guides

Use the setup guide that matches your client:

1. Codex CLI setup
2. CLI agent setup (Claude Code, generic MCP CLIs, Claude Desktop)
3. opencode setup
4. ChatGPT Custom GPT setup
5. Social publishing setup (TikTok / Facebook)

---

Codex quick setup

Add this block to ~/.codex/config.toml:

[mcp_servers.hermes]
url = "https://hermes.squaremcp.com/mcp"

See CODEX_SETUP.md for the full notes and caveats.

---

opencode quick setup

Project-level opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hermes": {
      "type": "remote",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_MCP_API_KEY"
      }
    }
  }
}

Full instructions: OPENCODE.md

---

Local development

npm install
cp .env.example .env
npm run dev
curl http://localhost:3456/health

The local server runs on port 3456 by default.

---

Deployment

Production deployment notes are in:

1. DEPLOY.md
2. hermes-k8s.yaml

SquareMCP product-site docs live under:

1. product/site
2. product/README.md
3. videos/remotion-demo for SquareMCP video production assets and render workflows

---

Notes

The historical docs in this repo started from an email-only Claude-focused setup. Current deployment and setup guidance should follow:

1. the hermes.squaremcp.com domain
2. Streamable HTTP /mcp as the default transport
3. the dedicated client setup docs linked above