Project History

November 16, 2025 · View on GitHub

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: Early prototypes with significant security flaws were abandoned rather than archived. The failed approaches included:

  • In-process sandbox attempts with unsafe builtins
  • RLIMIT-based isolation that was easily circumvented
  • Process spawning without proper isolation
  • Broken startup sequences and event loop violations
  • Various insecure execution patterns

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.
  • 2025-11 release: Corrected the stdio bridge startup by removing the stray stdio_server(app) call and began returning responses as proper CallToolResult objects (TOON text + mirrored structuredContent). The fix ships in the public package, so the uvx shim now reflects the latest behaviour.
  • 2025-11 update: Switched the default response renderer to compact plain text while keeping TOON blocks opt-in via MCP_BRIDGE_OUTPUT_MODE for scenarios that benefit from the structured format.

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

# Prototype approach
result = execute_insecurely(code)

New: Container-Based Execution

# Current approach
result = run_python(code, servers=['filesystem'])

Benefits:

  • Actual security isolation
  • Protocol compliance
  • Reliable error handling
  • Production readiness

References

External Inspiration

Internal Documentation

Acknowledgments

Thanks to reviewers and contributors who highlighted the failures in the prototypes. Their feedback was essential for the current robust implementation.

These failed approaches serve as valuable lessons demonstrating why security claims must be carefully validated and why architectural commitment to security is essential.

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