From 47b0db16e448d4364c31975468020ab24e06410a Mon Sep 17 00:00:00 2001
From: Sam & Claude <hello@clawdie.si>
Date: Sat, 13 Jun 2026 19:54:17 +0200
Subject: [PATCH] docs: add external MCP profile examples to ISO (Sam & Codex)

Adds sample external MCP registry and explicit external-call client profile alongside the default read-only Colibri MCP examples.\n\nChecks: ./scripts/check-format.sh; sh -n build.sh scripts/stage-colibri-iso.sh; python3 -m json.tool MCP examples; git diff --check
---
 live/operator-session/mcp-examples/README.md  | 42 +++++++++++++++++--
 .../mcp-examples/external-mcp.sample.json     | 16 +++++++
 .../mcp-examples/mcp-external-call.json       | 11 +++++
 3 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 live/operator-session/mcp-examples/external-mcp.sample.json
 create mode 100644 live/operator-session/mcp-examples/mcp-external-call.json

diff --git a/live/operator-session/mcp-examples/README.md b/live/operator-session/mcp-examples/README.md
index 1ff30f0..a02c8e5 100644
--- a/live/operator-session/mcp-examples/README.md
+++ b/live/operator-session/mcp-examples/README.md
@@ -4,15 +4,18 @@ The live USB includes `/usr/local/bin/colibri-mcp`, an MCP server that exposes
 Colibri status, glasspane snapshots, task lists, and skills to MCP-capable
 editors/assistants.
 
-Default posture is read-only. Write tools are available only when the MCP server
-process is launched with `COLIBRI_MCP_WRITE=1`.
+Default posture is read-only. Colibri write tools are available only when the
+MCP server process is launched with `COLIBRI_MCP_WRITE=1`. External MCP tool
+calls are available only when launched with `COLIBRI_MCP_EXTERNAL_CALL=1`.
 
 ## Generic MCP client config
 
 Most MCP clients accept a config shaped like `mcpServers`. Use one of:
 
 - `mcp-readonly.json` — safe default profile
-- `mcp-trusted-write.json` — explicit trusted profile with write tools enabled
+- `mcp-trusted-write.json` — explicit trusted profile with Colibri write tools enabled
+- `mcp-external-call.json` — explicit trusted profile for external MCP tool calls
+- `external-mcp.sample.json` — example external MCP server registry
 
 ## Quick checks
 
@@ -20,6 +23,8 @@ Most MCP clients accept a config shaped like `mcpServers`. Use one of:
 colibri-mcp tools
 COLIBRI_MCP_WRITE=1 colibri-mcp tools
 colibri-mcp socket-path
+COLIBRI_MCP_EXTERNAL_CONFIG=/usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
+  colibri-mcp tools
 ```
 
 ## Claude Code example
@@ -56,3 +61,34 @@ For a write-capable profile, add:
 ```
 
 Only enable the write profile for trusted workspaces/sessions.
+
+## External MCP server prototype
+
+Newer Colibri builds can also use `colibri-mcp` as a small MCP host/client for
+other stdio MCP servers. Copy the sample registry into the live config path and
+edit it for the servers you actually want:
+
+```sh
+mdo -u root mkdir -p /usr/local/etc/colibri
+mdo -u root cp /usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
+  /usr/local/etc/colibri/external-mcp.json
+```
+
+Read-only discovery works by default through these tools:
+
+- `colibri_external_mcp_servers`
+- `colibri_external_mcp_list_tools`
+
+Calling external MCP tools requires an explicit trusted profile:
+
+```json
+{
+  "command": "/usr/local/bin/colibri-mcp",
+  "args": [],
+  "env": {
+    "COLIBRI_MCP_EXTERNAL_CALL": "1"
+  }
+}
+```
+
+External MCP tool calls are intentionally separate from `COLIBRI_MCP_WRITE=1`.
diff --git a/live/operator-session/mcp-examples/external-mcp.sample.json b/live/operator-session/mcp-examples/external-mcp.sample.json
new file mode 100644
index 0000000..079057b
--- /dev/null
+++ b/live/operator-session/mcp-examples/external-mcp.sample.json
@@ -0,0 +1,16 @@
+{
+  "servers": {
+    "demo": {
+      "command": "/usr/local/bin/demo-mcp-server",
+      "args": ["--stdio"],
+      "env": {
+        "DEMO_MODE": "1"
+      }
+    },
+    "filesystem-example": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/clawdie"],
+      "env": {}
+    }
+  }
+}
diff --git a/live/operator-session/mcp-examples/mcp-external-call.json b/live/operator-session/mcp-examples/mcp-external-call.json
new file mode 100644
index 0000000..e93fad7
--- /dev/null
+++ b/live/operator-session/mcp-examples/mcp-external-call.json
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "colibri-external-call": {
+      "command": "/usr/local/bin/colibri-mcp",
+      "args": [],
+      "env": {
+        "COLIBRI_MCP_EXTERNAL_CALL": "1"
+      }
+    }
+  }
+}