Support Codex OAuth login and add CLI setup docs

2026-05-11 10:39:24 -04:00
parent ffb67560b9
commit 6bf4cfd069
6 changed files with 458 additions and 113 deletions
--- a/AGENTS_CLI_SETUP.md
+++ b/AGENTS_CLI_SETUP.md
@@ -0,0 +1,162 @@
+# Connecting Hermes MCP to CLI Agents
+
+Hermes exposes a Streamable HTTP MCP endpoint at:
+
+```text
+https://hermes.squaremcp.com/mcp
+```
+
+Legacy SSE is also available at:
+
+```text
+https://hermes.squaremcp.com/sse
+```
+
+Use your own credential value anywhere you see:
+
+```text
+YOUR_MCP_API_KEY
+```
+
+Never commit a live API key into repo config files.
+
+---
+
+## Claude Code
+
+Some Claude Code builds support MCP add/list commands and some require manual config.
+
+### If your Claude CLI supports `mcp add`
+
+```bash
+claude mcp add hermes \
+  --transport http \
+  https://hermes.squaremcp.com/mcp \
+  --header "x-api-key: YOUR_MCP_API_KEY"
+```
+
+### Manual config
+
+If your version does not support the CLI flow, add Hermes to:
+
+```text
+~/.claude/mcp.json
+```
+
+```json
+{
+  "mcpServers": {
+    "hermes": {
+      "url": "https://hermes.squaremcp.com/mcp",
+      "headers": {
+        "x-api-key": "YOUR_MCP_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Verify
+
+```bash
+claude mcp list
+```
+
+---
+
+## Claude Desktop
+
+Add Hermes to the Claude Desktop config:
+
+### macOS
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+### Linux
+
+```text
+~/.config/Claude/claude_desktop_config.json
+```
+
+### Windows
+
+```text
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+```json
+{
+  "mcpServers": {
+    "hermes": {
+      "url": "https://hermes.squaremcp.com/mcp",
+      "headers": {
+        "x-api-key": "YOUR_MCP_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the file.
+
+---
+
+## Generic MCP-capable CLI agents
+
+Many agent CLIs and editor plugins accept a JSON config file with an `mcpServers` block.
+
+Example portable config:
+
+```json
+{
+  "mcpServers": {
+    "hermes": {
+      "url": "https://hermes.squaremcp.com/mcp",
+      "headers": {
+        "x-api-key": "YOUR_MCP_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Typical usage pattern:
+
+```bash
+some-agent-cli --mcp-config-file ~/.mcp.json
+```
+
+Possible target clients include:
+
+1. custom MCP wrappers
+2. editor plugins that expose MCP server config
+3. internal agent CLIs that consume a shared JSON config
+
+---
+
+## SSE fallback
+
+If a client only supports SSE:
+
+```json
+{
+  "mcpServers": {
+    "hermes": {
+      "url": "https://hermes.squaremcp.com/sse",
+      "headers": {
+        "x-api-key": "YOUR_MCP_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Related docs
+
+1. [Codex CLI setup](./CODEX_SETUP.md)
+2. [opencode setup](./OPENCODE.md)
+3. [ChatGPT setup](./CHATGPT_SETUP.md)