mcp-exec

mcp-exec

Public OSS MCP server (Go, MIT) exposing a single powerful tool — exec — that runs caller-supplied Python code in a network-isolated, locked-down sandbox and returns stdout / stderr / exit_code. It is the "code-execution mode" building block: instead of flooding an agent's context with hundreds of tool schemas, the agent writes code that orchestrates the work.

Works over three transports — stdio / HTTP / SSE — with an identical tool set everywhere (official modelcontextprotocol/go-sdk).

The exec tool

Input: { code: string (required), timeout_s?: int, stdin?: string } Output: { stdout, stderr, exit_code, duration_ms, truncated, timed_out }

• A non-zero exit_code or timed_out=true is a normal result, not a tool error. Only invalid input (empty code, oversized stdin) is a tool-call error.
• Sandbox v1: Python 3 with stdlib + PyYAML + Jinja2.

Security model (invariants)

Per execution: no network, non-root, cap-drop=ALL, no-new-privileges, read-only rootfs, no CAP_SYS_ADMIN, ephemeral tmpdir (cleaned up), wall-clock timeout (kills the whole process-group), memory/PID/CPU limits, capped output (1 MiB → truncated). Runs are serialized within an instance; scale out with replicas. Caller data (code/stdin/output) is never persisted and never logged in full — only metadata.

exec is the most powerful surface there is. When embedding it in an agent, gate it behind that agent's tool-policy (trusted roles only).

Run

go build -o mcp-exec ./cmd/mcp-exec
MCP_EXEC_TRANSPORT=stdio ./mcp-exec

Docker (recommended production posture):

docker run --rm -i --network none --read-only --cap-drop ALL \
  --security-opt no-new-privileges --user 65532:65532 \
  --memory 256m --pids-limit 128 --cpus 1 \
  idconstruct/mcp-exec

Optional auth (HTTP/SSE)

Set MCP_EXEC_AUTH_TOKEN to require every HTTP/SSE request to carry a matching X-MCP-AUTH header (constant-time compare; 401 otherwise). Empty token disables it. Not applicable to stdio.

Configuration and the full env-var list live in CLAUDE.md; usage scenarios in specs/001-exec-tool-v1/quickstart.md.

Not in v1

bash / multi-language, network from the sandbox, proxying other MCP servers into the sandbox.

License

MIT.