Hermes MCP — SquareMCP Gateway

Hermes is the MCP server powering SquareMCP. It exposes 51 tools across 11 platforms (email, Obsidian, WhatsApp, LinkedIn, TikTok, Facebook, Instagram, Twitter, Telegram, Discord, Snapchat) over Streamable HTTP, with per-user authentication, OAuth 2.0, and multi-tenant credential isolation.

Production endpoint:

https://hermes.squaremcp.com/mcp

---

Quick connect

claude.ai

1. Settings → MCP Servers → Add → enter https://hermes.squaremcp.com
2. Complete the OAuth popup (login with your SquareMCP credentials)
3. Click "Connect MCP client"

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "squaremcp": {
      "type": "http",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Codex CLI

# ~/.codex/config.toml
[mcp_servers.squaremcp]
url = "https://hermes.squaremcp.com/mcp"
headers = { Authorization = "Bearer YOUR_TOKEN" }

opencode

{
  "mcp": {
    "squaremcp": {
      "type": "remote",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Get your token from the SquareMCP dashboard → Connect MCP Client.

---

Architecture

See ARCHITECTURE.md for the full architecture with diagrams.

                     nginx ingress (TLS)
                           │
              ┌────────────┼────────────┐
              │            │            │
        hermes-mcp    squaremcp-app  squaremcp-docs
        :3456          :8080          :80
        (MCP API)      (SaaS UI)     (Docs)
              │
    ┌─────────┼─────────┐
    │         │         │
  MySQL 8   Redis 7  /vaults
  (creds +  (cache +  (Obsidian)
  billing)   DLQ)

Stack: TypeScript / Node.js, Express, MySQL 8, Redis 7, MicroK8s, Docker Auth: JWT session cookies + OAuth 2.0 PKCE + API key Platform clients: 11 platforms, 51 MCP tools

---

Platforms

Platform	Tools
Email (IMAP/SMTP)	search, read, send, draft, folders
Obsidian	search, read, append, update, sync
WhatsApp Business	send, template, list templates
LinkedIn	profile, post, search connections, message, video
TikTok	profile, creator info, upload video, status
Facebook	page, posts, post, photo, video
Instagram	profile, media, post, reel
Twitter/X	profile, tweets, search, tweet, video
Telegram	me, send, photo, updates, chat
Discord	me, guilds, channels, send, messages
Snapchat	me, ad accounts, create snap

---

Authentication

Hermes accepts (in priority order):

1. x-api-key header — global superadmin or per-customer key
2. Authorization: Bearer <token> — JWT or OAuth access token
3. Cookie: session=<JWT> — web session (set by /api/auth/login or /login)

---

Transports

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

---

Client setup guides

• Codex CLI
• Claude Code / CLI agents
• opencode
• ChatGPT Custom GPT
• Social publishing (TikTok / Facebook)

---

Local development

npm install
cp .env.example .env   # fill in credentials
npm run dev
curl http://localhost:3456/health

Server runs on port 3456 by default.

---

Deployment

See DEPLOY.md for the full deployment runbook.

The short version:

npm run build
docker build -t localhost:32000/hermes-mcp:latest .
docker push localhost:32000/hermes-mcp:latest
# update sha256 digest in hermes-k8s.yaml
microk8s kubectl apply -f hermes-k8s.yaml