MCP Server Code Execution Mode

# Project History ## Evolution Summary The MCP Server Code Execution Mode bridge evolved through **failed prototypes** to a robust, production-capable **rootless container-based architecture**. The journey demonstrates the importance of security-first design and architectural discipline. ## Timeline ### Phase 1: In-Process Prototypes (Failed) Early iterations attempted to sandbox code using host-side techniques: **Archived Files** (see `archive/broken_prototypes/`): - `mini_codex.py` - No sandbox, event loop issues - `claude_prototype.py` - Process spawning, no isolation - `mcp_codex.py` - Broken startup, undeclared functions - `secure_codex.py` - "Safe builtins", still vulnerable - `proper_codex.py` - RLIMIT misapplication - `claude_prototype.py` - Additional failed attempt **Common Failures:** 1. **Security flaws** - Sandbox escapes through "safe" builtins 2. **Protocol mismatches** - Raw JSON vs length-prefixed messages 3. **I/O plumbing issues** - Event loop violations 4. **Misapplied limits** - RLIMIT on parent vs child 5. **In-process execution** - Always vulnerable to escalation ### Phase 2: Container-Based Architecture (Current) The pivot to rootless containers provided: - **Predictable isolation** without privileged helpers - **Host mediation** for all cross-boundary operations - **Clear boundaries** between sandbox and host - **Security-first design** over convenience - **2025 refinement**: Replaced the Unix-domain socket bridge with a JSON-over-stdio protocol to simplify container wiring and enable direct integration with Docker's MCP gateway. ## Key Lessons ### 1. Security Claims Must Match Reality **Lesson:** If a sandbox is leaky, disable it entirely. **Application:** Rootless containers with comprehensive constraints: - No network - Read-only rootfs - Dropped capabilities - Unprivileged user - Resource limits ### 2. Explicit Mediation Over Implicit Trust **Lesson:** All cross-boundary operations should be explicit and mediated. **Application:** - Host-side mediation via JSON-framed stdio - Explicit server allowlist enforcement - Input validation and defensive cleanup ### 3. Documentation Tracks Active Architecture **Lesson:** Docs must reflect reality, not aspirations. **Application:** - Removed obsolete socket documentation - Container-based architecture throughout - Security constraints clearly documented - Evolution path explained ### 4. Correctness Over Convenience **Lesson:** Secure and correct > fast and convenient. **Application:** - Fresh container per execution (stateless) - No state sharing between calls - Cleanup after each execution - Consistent isolation guarantees ## Current Architecture ### Design Principles 1. **Container boundaries** over process boundaries 2. **Host mediation** over in-process shortcuts 3. **Stateless execution** over stateful sessions 4. **Explicit configuration** over implicit behavior 5. **Defense in depth** over single security layer ### Core Components ``` ┌─────────────────────────────────────┐ │ Rootless Container Sandbox │ │ - Network: disabled │ │ - Filesystem: read-only │ │ - User: unprivileged │ │ - Capabilities: dropped │ └──────────────┬──────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Host-Mediated JSON Stdio Bridge │ │ - Line-delimited JSON frames │ │ - Request/response streaming │ │ - Forwarded by SandboxInvocation │ └──────────────┬──────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Persistent MCP Client Pool │ │ - Stays warm between calls │ │ - Auto-recovery on failure │ │ - Resource cleanup on shutdown │ └─────────────────────────────────────┘ ``` ## Migration Guide If you're familiar with the prototypes: ### Old: In-Process Execution ```python # Prototype approach result = execute_insecurely(code) ``` ### New: Container-Based Execution ```python # Current approach result = run_python(code, servers=['filesystem']) ``` **Benefits:** - Actual security isolation - Protocol compliance - Reliable error handling - Production readiness ## References ### External Inspiration - [Anthropic: Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) - [Cloudflare: Code Mode](https://blog.cloudflare.com/code-mode/) ### Internal Documentation - [README.md](README.md) - Current architecture - [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep dive - [STATUS.md](STATUS.md) - Implementation status ## Acknowledgments Thanks to reviewers and contributors who highlighted the failures in the prototypes. Their feedback was essential for the current robust implementation. The archived prototypes remain as a reference for what **not** to do and why security claims must be carefully validated. ## Conclusion This project's evolution demonstrates that: - **Failed approaches should be abandoned**, not patched - **Security requires architectural commitment**, not add-ons - **Documentation should reflect reality**, not intentions - **Correctness trumps convenience** in production systems The current implementation provides a solid foundation for secure MCP-enabled code execution. --- **Bottom Line:** Rootless containers + host mediation = secure, reliable code execution