2026 OpenClaw on a Remote Physical Mac: MCP stdio & Streamable HTTP—Reproducible Runbook (spawn ENOENT, Protocol Mismatch, Tool Timeouts + CLI + FAQ)

2. stdio vs Streamable HTTP: which transport when?

Pick the transport that minimizes moving parts on the same host, then graduate to HTTP when you must share a server or terminate auth at the proxy.

3. Seven-step reproducible rollout

1. Capture identity — Note the user that owns OpenClaw, the plist or LaunchAgent label, and the cwd from launchctl print / service unit.
2. Replay stdio without the gateway — As that user, run /bin/bash -lc 'which node; node -v' and the exact MCP command with env-file parity.
3. Harden stdio config — Absolute paths for command, explicit args, optional cwd, and explicit env (see JSON below).
4. Optional HTTP path — Bind MCP HTTP to 127.0.0.1, terminate TLS on nginx/Caddy, and verify curl -v shows the expected Accept negotiation.
5. Version lock — Pin the MCP SDK / server package to the same major.minor as the client library inside OpenClaw; record both in your changelog.
6. Timeout budget — Measure tools/call P95 with realistic inputs; set client wait ≥ P95 × 1.5 with a hard cap.
7. Log contracts — Emit one JSON line per initialize, tools/list, and tools/call with a shared correlation id.

For always-on agent flows that must survive restarts, align this runbook with the automation patterns in OpenClaw 24/7 automation on ZoneMac physical nodes.

4. CLI configuration fragments (illustrative JSON)

Adapt keys to your OpenClaw or host config schema; the important part is absolute paths and explicit environment blocks.

{
  "mcpServers": {
    "repo-tools": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/usr/local/lib/mcp-servers/repo-tools/dist/main.js"],
      "cwd": "/Users/shared/mcp/repo-tools",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "legacy-npx": {
      "command": "/bin/bash",
      "args": ["-lc", "exec npx --yes @example/[email protected]"],
      "env": { "HOME": "/Users/shared" }
    }
  }
}

{
  "mcpServers": {
    "http-shared": {
      "url": "https://mcp.internal.example.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_EDGE_TOKEN}"
      }
    }
  }
}

5. Symptom runbooks

5.1 spawn ENOENT (stdio)

5.2 Protocol version / 406 (Streamable HTTP)

Compare server and client handshake logs side by side. If the server expects text/event-stream but the proxy injects gzip without flushing, clients stall with “version mismatch” even though semver looks aligned.

5.3 Tool timeouts

Chart three timers: (A) model/tool-router wait, (B) gateway upstream deadline, (C) MCP server internal job timeout. Adjust the tightest layer first, then widen adjacent layers only if traces prove queuing.

6. Numbers you can paste into SLO docs

• ~4W — Apple Silicon Mac mini idle draw while holding SSH + lightweight gateways—useful for TCO models against x86 towers that idle much higher.
• 25s — Rule-of-thumb ceiling for “fast” tools/call P95 on shared nodes; beyond this, split tools or stream partial results instead of raising timeouts indefinitely.
• 600s — Long-running maintenance tools (large repo scans) should move to async jobs with polling, not a single blocking MCP call—mirrors how we treat long Git/npm operations in CI mirrors.

7. FAQ