clawdie-iso/docs/USB-MOTHER-MCP-CONNECTION.md

USB → Mother MCP Connection Plan

23.jun.2026 | Implementation plan | No code yet

Goal

Boot the live USB, and the colibri-daemon automatically connects to mother (OSA) via MCP over SSH. The first action on autospawn: clawdie-hw-probe runs, hardware profile is sent to mother via colibri_external_mcp_call_tool, and mother stores it in PostgreSQL mother_hive.hive_nodes.

Current state

Component	USB (0.11)	OSA (mother)
colibri-daemon	✅ Running, 0.11 binary	✅ Running, 0.11 binary
External MCP support	✅ Built-in (colibri_external_mcp_call_tool)	✅ Built-in
COLIBRI_MCP_EXTERNAL_CALL	❌ Not set	✅ 1
external-mcp.json	❌ Doesn't exist	✅ mother-build + geodesic-dome
mother-mcp SSH key	❌ Not present	✅ /var/db/colibri/.ssh/mother-mcp
SSH config for mother	❌ None	✅ localhost test confirmed
clawdie-hw-probe	❌ Not installed (0.12 feature)	✅ Works, produces valid JSON
PostgreSQL mother_hive	N/A	✅ OSA node registered

What the USB needs (5 steps)

Step 1: SSH key + config

The USB needs the mother-mcp private key so it can SSH to mother as colibri. The key should come from the seed partition — the operator places it on CLAWDIESEED before first boot. For testing: copy manually.

# On USB, as clawdie:
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Copy mother-mcp private key (from seed or scp)
# The public key is already in mother's authorized_keys:
#   command="/usr/local/bin/colibri-mcp-ssh",restrict,...

cat > ~/.ssh/mother-mcp << 'KEY'
<private key content>
KEY
chmod 600 ~/.ssh/mother-mcp

# SSH config for Tailscale hostname
cat >> ~/.ssh/config << 'SSH'
Host mother
    HostName <mother-tailscale-ip>
    User colibri
    IdentityFile ~/.ssh/mother-mcp
    IdentitiesOnly yes
    StrictHostKeyChecking accept-new
SSH
chmod 600 ~/.ssh/config

# Test: should list MCP tools
ssh mother 'tools' 2>&1 | head -5

Step 2: Enable external MCP calls

# Already in provider.env.sample for 0.12, add manually on 0.11:
sudo tee -a /usr/local/etc/colibri/provider.env << 'ENV'
COLIBRI_MCP_EXTERNAL_CALL=1
ENV

Step 3: Register mother as external MCP server

sudo tee /usr/local/etc/colibri/external-mcp.json << 'JSON'
{
  "servers": {
    "mother": {
      "command": "ssh",
      "args": [
        "-i", "/home/clawdie/.ssh/mother-mcp",
        "-o", "StrictHostKeyChecking=accept-new",
        "colibri@<mother-tailscale-ip>",
        "colibri-mcp"
      ],
      "env": {}
    }
  }
}
JSON

How this works: the USB daemon spawns ssh colibri@mother colibri-mcp as a persistent child process. JSON-RPC is piped over stdin/stdout. The mother-side colibri-mcp-ssh wrapper (in authorized_keys command=) strips the wrapper layer and passes commands directly to colibri-mcp. A single SSH connection stays alive for the daemon's lifetime.

Step 4: Install clawdie-hw-probe

# From the 0.12 feature branch (on USB or scp from OSA):
# Already committed to clawdie-iso/live/operator-session/clawdie-hw-probe
sudo install -m 755 /home/clawdie/ai/clawdie-iso/live/operator-session/clawdie-hw-probe \
    /usr/local/bin/clawdie-hw-probe

# Test:
sudo clawdie-hw-probe | python3.11 -m json.tool | head -10

Step 5: Restart daemon + verify

sudo service colibri_daemon restart

# Verify external MCP is connected:
colibri-mcp tools 2>&1 | grep external
# Should show:
#   colibri_external_mcp_servers
#   colibri_external_mcp_list_tools
#   colibri_external_mcp_call_tool

# List mother's tools:
colibri-mcp --external-config /usr/local/etc/colibri/external-mcp.json \
    --external-call tools 2>&1 | head -10

End-to-end test

# 1. Run hw-probe
HW_JSON=$(sudo clawdie-hw-probe 2>/dev/null)

# 2. Send to mother via MCP call
# (through colibri daemon's external MCP — needs the daemon to be running
#  with the mother server registered)

# 3. Verify on mother:
sudo -u postgres psql -d mother_hive -c "SELECT hostname, status, capabilities FROM hive_nodes;"

Expected: the USB node appears in PostgreSQL with hardware profile and derived capabilities (has_gpu, ram_gb, cpu_cores, etc.).

Open questions

1. SSH key persistence: The seed partition should stage the key on CLAWDIESEED so the operator doesn't manually copy it. The seed importer (clawdie-live-seed) already supports <agent>/ssh/<keyname> files. The operator places mother-mcp and mother-mcp.pub in the seed dir, reboots, and the key is automatically installed.

2. Autospawn integration: In 0.12, the daemon collects clawdie-hw-probe at autospawn time and passes it to the agent as CLAWDIE_HW_PROFILE env var. The agent's first action should read that env var and call colibri_external_mcp_call_tool(server="mother", tool="node_register"). The node_register MCP tool is now implemented at the colibri repo (packaging/mother/node-register-mcp).

3. Tailscale dependency: The USB needs Tailscale to be up before MCP works. This is already the case — Tailscale auth is part of the bootstrap flow. Without Tailscale, the USB can't reach mother at its Tailscale IP.

Implementation priority

Step	Effort	Blocked by
Step 1: SSH key + config	Manual (one-time)	Nothing
Step 2: Enable external MCP	1 line	Nothing
Step 3: external-mcp.json	10 lines JSON	Nothing
Step 4: Install hw-probe	Copy file	0.12 branch
Step 5: Restart + verify	2 commands	Steps 1-4
Step 6: Seed partition auto-key	Code change	0.12 ISO build	\n	Step 7: Install node_register on mother	Copy + psql grant	Steps 1-5