feat(sandbox): MCP server isolation via Unix socket bridge

[decko]

Context

Sub-issue of #568. Depends on #640 (MCP sandbox support). Future improvement over #640's "disable netns" approach.

Summary

Run MCP servers outside the sandbox and bridge communication via Unix sockets, providing full network isolation for the agent while MCP servers retain host network access.

Design

Architecture

Host                              Sandbox (Landlock + seccomp + cgroups + netns)
  |                                  |
  MCP Server (jira)  <--Unix socket-->  Claude Code / Opencode
  MCP Server (github) <--Unix socket-->   (network namespace: loopback only)
  |                                  |
  Host network                       No host network

How it works

1. SODA starts MCP servers on the host side before launching the sandbox
2. Each MCP server listens on a Unix socket in a temp directory
3. The socket directory is added to the sandbox's read+write paths
4. The --mcp-config points to server entries with transport: "unix" socket paths
5. Agent inside sandbox connects to MCP servers via the socket
6. SODA manages MCP server lifecycle (start before phase, stop after)

Prerequisites

• go-arapuca NetworkProxySocket support (available since v0.3.0, feat(sandbox): enable network namespace isolation once go-arapuca implements socket bridge #340 closed)
• Claude Code support for MCP over Unix socket transport
• Opencode support for MCP over Unix socket transport (may need upstream contribution)

MCP server manager

New internal/mcp/ package:

type ServerManager struct {
    servers map[string]*runningServer
}

func (m *ServerManager) Start(ctx context.Context, name string, cfg MCPServerConfig) (socketPath string, err error)
func (m *ServerManager) Stop(name string) error
func (m *ServerManager) StopAll()
func (m *ServerManager) HealthCheck(name string) error

Fallback

If Unix socket transport is not supported by the agent CLI, fall back to #640's approach (disable netns, run MCP inside sandbox). Log which mode is active.

Acceptance criteria

• internal/mcp/ package with ServerManager
• MCP servers started on host side with Unix socket transport
• Socket paths passed to sandbox read+write paths
• Agent connects to MCP via socket from inside sandbox
• Network namespace remains enabled (full isolation)
• Graceful fallback to feat(sandbox): MCP server support inside arapuca sandbox #640 approach when socket transport unavailable
• Health check verifies MCP server is responding on socket
• MCP server lifecycle tied to phase execution (start/stop)
• Tests: server lifecycle, socket communication, fallback

Estimated token budget

• Read: ~10K (sandbox, mcp protocol, go-arapuca)
• Write: ~15K (server manager, socket bridge, lifecycle, tests)
• Total: ~70K / 80K

Depends on

• feat(sandbox): MCP server support inside arapuca sandbox #640 (MCP sandbox inside -- fallback path)
• go-arapuca Unix socket bridge support
• Upstream: Claude Code Unix socket MCP transport

[decko]

Update: SSE transport as alternative to Unix sockets.

SSE bridge option

Opencode natively supports SSE transport for MCP servers. Instead of (or in addition to) Unix socket bridging, SODA could:

1. Start MCP servers on the host side as stdio subprocesses
2. Wrap each in a lightweight stdio-to-SSE adapter (HTTP server on localhost)
3. Point the in-sandbox agent at http://localhost:<port>/mcp via SSE config

Host                                  Sandbox
  |                                     |
  MCP Server (stdio)                    Agent (Claude/Opencode)
    ↕ stdin/stdout                        ↕ HTTP
  SSE Adapter (localhost:N)  ←────────→  --mcp-config / .opencode.json
    ↕ HTTP                                 (type: sse, url: http://localhost:N)

Advantages over Unix sockets

• Works with both Claude Code and Opencode without upstream changes
• HTTP is a standard transport — no agent-specific socket support needed
• Similar pattern to the existing Vertex proxy (SODA already runs localhost HTTP proxies)
• go-arapuca NetworkProxySocket not required

Disadvantages

• Extra HTTP layer (latency, though negligible for MCP tool calls)
• Need to manage port allocation per MCP server
• Auth between sandbox and host SSE adapter (could use bearer token on loopback)

Recommendation

Consider SSE adapter as the primary bridge transport instead of Unix sockets. It reuses patterns SODA already has (proxy infrastructure) and works across all agent backends without upstream dependencies.

Unix socket bridge remains a future option if performance matters or go-arapuca exposes a clean socket passthrough API.

[decko]

Updated findings after netns bridge verification (2026-07-01)

What works today (verified)

• ✅ NetNS loopback UP — confirmed with arapuca v0.2.4 (--map-root-user)
• ✅ NetworkProxySocket bridge — TCP 127.0.0.1:18080 inside sandbox relays to host Unix socket
• ✅ Bridge fully functional end-to-end with SeccompProfileBaseline

Why the original spec needs revision

The original spec assumes MCP servers communicate via Unix socket transport from inside the sandbox (transport: "unix" in --mcp-config). Claude Code does not support Unix socket transport for MCP — only HTTP/HTTPS/stdio.

Two viable paths

Path A: CONNECT proxy via --allow-host (preferred, needs go-arapuca work)

arapuca's --allow-host H:P flag creates a CONNECT proxy inside the netns that allows outbound connections to specific host:port pairs. SODA would:

1. Start MCP servers on host at known ports (stdio → HTTP adapter)
2. Pass AllowedHosts to go-arapuca Config (not yet in API)
3. Inside sandbox: agent connects to http://mcp-server-name:PORT via CONNECT proxy
4. CONNECT proxy validates against allowlist and relays to host

Blocker: AllowedHost[] is not exposed in go-arapuca Config. Needs a PR to go-arapuca similar to SeccompProfile.

Path B: MCP over LLM proxy (works today, no new infra)

SODA's existing LLM proxy (on the host Unix socket, bridged via port 18080) could be extended to also proxy MCP tool calls:

1. MCP servers run on host as stdio processes (managed by SODA)
2. Agent makes MCP tool calls → they arrive at the proxy (port 18080)
3. Proxy routes based on path prefix: /v1/messages → LLM, /mcp/jira/... → MCP server
4. Works with existing bridge infrastructure, no new arapuca features needed

Tradeoff: MCP traffic goes through the LLM proxy rather than direct agent→MCP connections. Adds latency. Also mixes LLM and MCP concerns in the proxy.

Revised acceptance criteria

• Path A (preferred): File go-arapuca PR to expose AllowedHosts []AllowedHost in Config, matching the arapuca_config_set_connect_proxy C API
• Start MCP servers on host side as HTTP processes (stdio-to-HTTP adapter)
• Pass allowed host:port pairs to sandbox config per phase
• Agent connects to MCP servers via CONNECT proxy inside sandbox
• Fallback to feat(sandbox): MCP server support inside arapuca sandbox #640 approach (disable netns) if CONNECT proxy unavailable
• Tests: server lifecycle, CONNECT proxy routing, fallback

Next action

File go-arapuca PR to expose --allow-host / AllowedHost[] in the Go Config. This is a small addition similar to SeccompProfile — one new field + C FFI call.

[decko]

Moving to v0.9.0. Blocked on:

• feat: expose connect proxy (--allow-host) in library FFI for go-arapuca callers sergio-correia/arapuca#45 — expose arapuca_config_add_allowed_host in C FFI
• feat: add AllowedHost type and Config.AllowedHosts for CONNECT proxy support sergio-correia/go-arapuca#4 — wire AllowedHosts in go-arapuca (open, ready to complete once feat(pipeline): create worktree before first phase runs #45 lands)

The bridge infrastructure is fully working (verified with arapuca v0.2.4 + Baseline seccomp). Implementation is unblocked as soon as the upstream FFI lands.