From 9e1620a9c52448bdd11819c24a9bc35892f86463 Mon Sep 17 00:00:00 2001
From: Markus Fritsche <marfrit@reauktion.de>
Date: Thu, 9 Jul 2026 16:06:50 +0000
Subject: [PATCH] Codex MCP server findings: emits 2 tools (codex,
 codex-reply). Document wiring options and existing pi MCP client config

---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 82 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 515d0fe..a610a46 100644
--- a/README.md
+++ b/README.md
@@ -37,12 +37,12 @@ Each agent is independent — separate host, separate Incus container, separate
 
 ## Agents
 
-| Agent | CLI | Invocation | Transport | Location |
-|-------|-----|------------|-----------|----------|
-| **Hermes** | `hermes` | n/a (orchestrator) | — | hertz |
-| **pi** | `pi --print` | `pi_exec` MCP tool, SSH+nohup | MCP / SSH | pica (Incus) |
-| **opencode** | `opencode run` | SSH / lmcp / direct terminal | SSH / MCP | orca.fritz.box (Incus) |
-| **claude-code** | `claude` | SSH / lmcp / direct terminal | SSH / MCP | noether.fritz.box (Incus) |
+| Agent | CLI | Invocation | Transport | Location | MCP Client | MCP Server |
+|-------|-----|------------|-----------|----------|-----------|------------|
+| **Hermes** | `hermes` | n/a (orchestrator) | — | hertz | stash, boltzmann, pica | `hermes mcp serve` |
+| **pi** | `pi --print` | `pi_exec` MCP tool, SSH+nohup | MCP / SSH | pica (Incus) | stash, hertz, boltzmann | `codex mcp-server` (2 tools) |
+| **opencode** | `opencode run` | SSH / lmcp / direct terminal | SSH / MCP | orca.fritz.box (Incus) | stash (configurable) | `opencode serve` |
+| **claude-code** | `claude` | SSH / lmcp / direct terminal | SSH / MCP | noether.fritz.box (Incus) | stash (via claude.json) | — |
 
 ## Invocation Patterns
 
@@ -95,10 +95,85 @@ ssh -f mfritsche@orca "opencode run 'Long task' > /tmp/opencode.log 2>&1"
 ssh -f mfritsche@noether "claude execute -p 'Long task' > /tmp/claude.log 2>&1"
 
 # Or via lmcp with shell_bg on either host
-curl -s http://orca.fritz.box:8080/mcp -H "Authorization: Bearer <token>" \
+curl -s http://orca.fritz.box:8080/mcp -H "Authorization: Bearer ***" \
   -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"shell_bg","arguments":{"command":"opencode run '...'","log":"/tmp/opencode-task.log"}}}'
 ```
 
+## Codex as MCP Server
+
+The official `codex` CLI (v0.143+) can run as an stdio MCP server, exposing pi's coding capabilities as callable tools. Start it on pica:
+
+```
+codex mcp-server --config model="o4-mini"
+```
+
+Handshake exposes:
+- Server: `codex-mcp-server` v0.143.0
+- Protocol: 2024-11-05
+- Capabilities: `tools.listChanged`
+
+### Exposed Tools
+
+**`codex`** — Start a session
+```
+Input:  prompt (required), model?, cwd?, sandbox?,
+        approval-policy?, base-instructions?,
+        developer-instructions?, config?
+Output: { threadId, content }
+```
+
+**`codex-reply`** — Continue a conversation
+```
+Input:  threadId (required), prompt (required)
+Output: { threadId, content }
+```
+
+### Wiring into Hermes
+
+Add the stdio server to Hermes's `config.yaml`:
+```yaml
+mcp_servers:
+  codex-pica:
+    command: ssh
+    args: [mfritsche@pica, /home/mfritsche/.local/share/pi-node/current/bin/codex, mcp-server]
+```
+
+Then `mcp__codex_pica__codex` and `mcp__codex_pica__codex_reply` appear as native Hermes tools.
+
+### Wiring into opencode
+
+In `~/.config/opencode/opencode.jsonc` on orca:
+```jsonc
+"mcp": {
+  "codex": {
+    "type": "local",
+    "command": ["ssh", "mfritsche@pica", "/home/mfritsche/.local/share/pi-node/current/bin/codex", "mcp-server"],
+    "enabled": true
+  }
+}
+```
+
+### Current pi Setup on pica
+
+Two installations coexist:
+| Version | Binary | MCP Server? | Notes |
+|---------|--------|-------------|-------|
+| `@earendil-works/pi-coding-agent` v0.80.3 | `pi` | No (--mode rpc only) | Community fork, NPU inference, MCP *client* |
+| `@openai/codex` v0.143.0 | `codex` | Yes (`codex mcp-server`) | Official OpenAI CLI, needs API key |
+
+pi (community fork) is already configured as an MCP *client* connected to stash, hertz, and boltzmann:
+```jsonc
+// ~/.pi/agent/mcp.json
+{
+  "mcpServers": {
+    "stash":    { "url": "http://192.168.88.184:8080/sse" },
+    "hertz":    { "url": "http://hertz.fritz.box:8080/mcp",
+                  "directTools": ["write_file","shell_bg","shell","fetch","web_search"] },
+    "boltzmann":{ "url": "http://boltzmann.fritz.box:8080/mcp" }
+  }
+}
+```
+
 ## Shared Memory Patterns
 
 ### Tier 1: Hermes Holographic Memory (Hermes-only)