Files

Garfield 02398258a5 feat: native OAuth login page, architecture docs, docs site update

- Add GET/POST /login to hermes for first-party cookie during OAuth popup
  (fixes browser CHIPS cookie partitioning that broke claude.ai connection)
- Add role column to all findCustomer* SQL queries in src/auth.ts
- Add claude.ai tab to docs/getting-started.html with OAuth flow steps
- Add ARCHITECTURE.md with system diagrams, data flow, and key invariants
- Rewrite README.md and DEPLOY.md to reflect actual MicroK8s deployment
- Deploy updated docs site (squaremcp-docs sha256 updated)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-14 13:48:01 -04:00

4.0 KiB

Raw Permalink Blame History

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

Settings → MCP Servers → Add → enter https://hermes.squaremcp.com
Complete the OAuth popup (login with your SquareMCP credentials)
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):

x-api-key header — global superadmin or per-customer key
Authorization: Bearer <token> — JWT or OAuth access token
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

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

4.0 KiB Raw Permalink Blame History