Project History & Evolution
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Server Code Execution Mode bridge represents an evolution from insecure, in-process prototyping toward a production-ready, rootless container-based architecture. Its primary purpose is to implement the "Code Execution with MCP" pattern, which significantly reduces LLM context overhead by replacing hundreds of individual tool schemas with a single run_python tool. This enables agents to discover and orchestrate tools dynamically through generated Python code rather than pre-loading massive JSON definitions.
The project aligns with the "Code Mode" philosophies popularized by Anthropic, Cloudflare, and Apple (CodeAct), prioritizing security-first design, host-mediated execution, and stateless sandboxing. By utilizing rootless containers, the system provides a hardened boundary that protects the host while allowing the LLM to perform complex data analysis and multi-step tool orchestration.
Sources: HISTORY.md:3-8, README.md:15-32, ARCHITECTURE.md:3-6
Phase 1: In-Process Prototypes (Abandoned)
The earliest iterations of the project attempted to sandbox code using host-side techniques. These approaches were eventually abandoned due to fundamental security and architectural flaws that could not be adequately patched.
Common Failure Points
Early development encountered several critical issues that led to the pivot toward containerization:
- Sandbox Escapes: In-process attempts using unsafe builtins proved vulnerable to escalation.
- Protocol Mismatches: Difficulty managing raw JSON versus length-prefixed messages.
- I/O Plumbing: Violations of the event loop occurred during process spawning.
- Misapplied Limits: Using
RLIMITon parent processes instead of children proved ineffective for isolation.
Sources: HISTORY.md:12-23
Phase 2: Container-Based Architecture
The current architecture represents a pivot to rootless containers, providing predictable isolation without requiring privileged helpers. This phase established clear boundaries between the sandbox and the host system.
Evolution of the Stdio Bridge
In 2025, the architecture was refined to simplify container wiring and integration:
- Protocol Switch: Replaced the Unix-domain socket bridge with a JSON-over-stdio protocol.
- Direct Integration: Enabled direct compatibility with Docker's MCP gateway.
- Startup Fixes: Corrected the stdio bridge by removing stray
stdio_server(app)calls and ensuring responses were returned as properCallToolResultobjects containing bothTextContentandstructuredContent.
Sources: HISTORY.md:27-42, STATUS.md:13-19
Architectural Transition Flow
The following diagram illustrates the shift from the vulnerable in-process model to the secure containerized model:
The transition moved security from "Soft" process-level isolation to "Hard" container isolation with dropped capabilities and no network access.
Sources: HISTORY.md:27-32, README.md:43-55, ARCHITECTURE.md:8-30
Key Evolution Lessons
The development history emphasizes four core lessons that guided the current implementation:
| Lesson | Application in Current Architecture |
|---|---|
| Security Match Reality | If a sandbox is leaky, it is disabled. Current implementation uses rootless containers with no network and read-only rootfs. |
| Explicit Mediation | All cross-boundary operations are mediated via JSON-framed stdio and server allowlists. |
| Documentation Realism | Obsolete socket documentation was removed to reflect the active container-based reality. |
| Correctness > Convenience | fresh containers are used per execution (stateless) to ensure cleanup and consistent guarantees. |
| Sources: HISTORY.md:46-75 |
Feature Maturation & Roadmap
The project has reached a "Production-Capable" status with a focus on operational hardening. While the core execution engine is functional, the evolution continues through priority enhancements.
Current Status vs. Roadmap
- Delivered: Rootless sandbox, persistent MCP sessions, memory system (
save_memory,load_memory), and discovery helpers (discovered_servers()). - In Progress: Expanded automated testing for RPC error handling, structured logging with request IDs, and agent-visible discovery channels (
mcp-find). - Future: Multi-language support, connection pooling for MCP clients, and shareable code-mode artifacts.
Sources: STATUS.md:10-55, README.md:280-300
Discovery Logic Evolution
One of the most significant evolutions was the Zero-Context Discovery pattern. Initially, MCP tools often preloaded all schemas, leading to "token bankruptcy." The bridge evolved to maintain a constant 200-token overhead.
This flow ensures that tool schemas flow to the LLM only when specifically requested via query_tool_docs().
Sources: README.md:65-90, mcp_server_code_execution_mode.py:640-700, ARCHITECTURE.md:32-55
Conclusion
The evolution of the MCP Server Code Execution Mode bridge is a case study in transitioning from convenient but insecure prototypes to a robust, architecture-first security model. By moving from in-process execution to host-mediated container sandboxes, the project provides a reliable foundation for LLM-driven tool orchestration without sacrificing host security or token efficiency.
Sources: HISTORY.md:92-100, STATUS.md:85-90