From 89e38e3ba390ec5e489374346d317133511a0888 Mon Sep 17 00:00:00 2001
From: Leonard <leonard@hermes.local>
Date: Sat, 20 Jun 2026 19:55:55 +0000
Subject: [PATCH] docs: add Hermes MCP server connection config for Grok

---
 agent-config/hermes-mcp-server.md | 104 ++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 agent-config/hermes-mcp-server.md

diff --git a/agent-config/hermes-mcp-server.md b/agent-config/hermes-mcp-server.md
new file mode 100644
index 0000000..a54a10b
--- /dev/null
+++ b/agent-config/hermes-mcp-server.md
@@ -0,0 +1,104 @@
+# Hermes MCP Server — Leonard Profile
+
+Direct MCP endpoint for Grok (or any MCP client) to connect to Hermes/Leonard's tools.
+
+## Connection Info
+
+| Field | Value |
+|-------|-------|
+| **Endpoint** | `http://74.208.111.99:8092/mcp` |
+| **Protocol** | MCP over HTTP SSE (StreamableHTTP) |
+| **Profile** | leonard |
+| **Status** | ✅ Live |
+
+## How Grok Connects
+
+Configure Grok's MCP client with the following:
+
+```yaml
+# In Grok's MCP config (e.g., config.yaml, agent config, or CLI flag):
+mcp_servers:
+  hermes-leonard:
+    url: "http://74.208.111.99:8092/mcp"
+    # No auth token needed — local network
+    # Optional: add a timeout if connection is slow
+    timeout: 120
+    connect_timeout: 60
+```
+
+Or via CLI if Grok supports direct MCP URL attachment:
+
+```
+--mcp-url http://74.208.111.99:8092/mcp
+```
+
+## Available Tools (7)
+
+| Tool | What It Does |
+|------|-------------|
+| `read_file` | Read any text file on the server by absolute path |
+| `search_files` | Search file contents with regex or glob patterns |
+| `list_directory` | List files and directories at a given path |
+| `git_log` | View recent git commit history in any repo |
+| `gitea_read_file` | Read a file from Gitea (any org/repo) directly via API |
+| `gitea_list_repos` | List all repos in a Gitea organization |
+| `run_shell` | Execute shell commands (read-only ops suggested) |
+
+## What Grok Can Do With This
+
+- **Read** any file in the personal-agent-os repo, chess-project, or any Gitea repo
+- **Search** across all files for patterns, tags, or keywords
+- **Check git history** — see who committed what and when
+- **List repos** — discover what's available in Tony_tech and Ty_Tech
+- **Run shell commands** — inspect system state, check services, run npm builds
+
+## Host Details
+
+| Detail | Value |
+|--------|-------|
+| Server IP | `74.208.111.99` |
+| Port | `8092` |
+| Localhost | `http://localhost:8092/mcp` |
+| Network | Open on `0.0.0.0:8092` — accessible from same network |
+| Runtime | systemd user service: `hermes-mcp-leonard` |
+| Auto-start | ✅ Enabled — starts on boot |
+
+## Verification
+
+```bash
+# Health check
+curl http://74.208.111.99:8092/health
+
+# List available tools
+curl http://74.208.111.99:8092/tools
+```
+
+## Architecture
+
+```
+Grok ──MCP/SSE──→ Hermes MCP Server (:8092) ──→ Hermes Tools
+                                                     │
+                          ┌──────────────────────────┘
+                          ▼
+                    Gitea MCP (:8081) ──→ Gitea Instance
+                    Local Filesystem
+                    Shell / System
+```
+
+## Security Notes
+
+- No authentication on the MCP endpoint (local/internal network)
+- `run_shell` is exposed — only connect trusted clients (Grok)
+- All Gitea reads go through the public API (no token needed for public repos)
+- To add auth, wrap the endpoint behind an nginx reverse proxy with basic auth
+
+## Troubleshooting
+
+**"Connection refused"** — the server may have been restarted. Run:
+```bash
+systemctl --user restart hermes-mcp-leonard
+```
+
+**"Tool not found"** — ensure the MCP client is using SSE transport, not stdio. The endpoint must be accessed as an HTTP SSE stream.
+
+**Slow responses** — increase `timeout` to 180s in the MCP client config for long running commands.
\ No newline at end of file