a5e4c55885
- JWT auth with bcrypt password hashing, cookie sessions, forgot/reset password - Per-user encrypted credential storage (Redis + AES-256-GCM) for all 9 platforms - Usage tracking with monthly limits per plan (free/starter/growth/enterprise) - Invoice generation and retrieval (admin + user views) - Admin panel with customer listing (role-based access) - Web app UI at app.squaremcp.com — login, dashboard, connections, usage, invoices - Unified auth middleware: API key, OAuth Bearer, and JWT cookie support - Facebook Graph API fixes: published_posts endpoint, photo/video post support - TikTok sandbox compliance: SELF_ONLY privacy for unaudited apps - URL verification files for TikTok app review
144 lines
2.9 KiB
Markdown
144 lines
2.9 KiB
Markdown
# Hermes MCP
|
|
|
|
Hermes MCP is a hosted MCP gateway for messaging, knowledge, and social connectors.
|
|
|
|
The production endpoint is:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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](./CODEX_SETUP.md)
|
|
2. [CLI agent setup (Claude Code, generic MCP CLIs, Claude Desktop)](./AGENTS_CLI_SETUP.md)
|
|
3. [opencode setup](./OPENCODE.md)
|
|
4. [ChatGPT Custom GPT setup](./CHATGPT_SETUP.md)
|
|
5. [Social publishing setup (TikTok / Facebook)](./SOCIAL_PUBLISHING_SETUP.md)
|
|
|
|
---
|
|
|
|
## Codex quick setup
|
|
|
|
Add this block to `~/.codex/config.toml`:
|
|
|
|
```toml
|
|
[mcp_servers.hermes]
|
|
url = "https://hermes.squaremcp.com/mcp"
|
|
```
|
|
|
|
See [CODEX_SETUP.md](./CODEX_SETUP.md) for the full notes and caveats.
|
|
|
|
---
|
|
|
|
## opencode quick setup
|
|
|
|
Project-level `opencode.json`:
|
|
|
|
```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](./OPENCODE.md)
|
|
|
|
---
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
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](./DEPLOY.md)
|
|
2. `hermes-k8s.yaml`
|
|
|
|
SquareMCP product-site docs live under:
|
|
|
|
1. [`product/site`](./product/site)
|
|
2. [`product/README.md`](./product/README.md)
|
|
3. [`videos/remotion-demo`](./videos/remotion-demo/README.md) 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
|