Logging & Diagnostics

Relevant source files

The following files were used as context for generating this wiki page:

• mcp_server_code_execution_mode.py
• GUIDE.md
• README.md
• ARCHITECTURE.md
• STATUS.md
• tests/test_entrypoint.py

Logging and diagnostics in the MCP Server Code Execution Mode bridge provide visibility into the orchestration of sandboxed Python environments, the proxying of Model Context Protocol (MCP) tool calls, and the lifecycle of containerized runtimes. The system utilizes standard Python logging alongside structured JSON-framed messaging to capture execution output, manage error states, and monitor the health of persistent MCP client sessions.

The diagnostics infrastructure focuses on three primary areas: bridge-level operational logging, sandboxed execution output (stdout/stderr), and runtime environment validation (Podman/Docker). This ensures that developers and agents can troubleshoot execution failures, timeout issues, and resource limit violations effectively.

Architecture & Data Flow

The diagnostic system operates across the boundary between the host bridge and the containerized sandbox. The bridge captures high-level operational events, while specific tool execution diagnostics are streamed via a JSON-framed stdio bridge.

Standard Bridge Logging

The bridge uses the standard Python logging library, identified by the name mcp-server-code-execution-mode. The default log level is INFO, but it can be adjusted via environment variables.

Configuration	Variable	Default	Description
Log Level	MCP_BRIDGE_LOG_LEVEL	INFO	Controls verbosity (DEBUG, INFO, WARNING, ERROR).
Runtime Detection	MCP_BRIDGE_RUNTIME	auto	Logs detected runtime (Podman/Docker).

Sources: mcp_server_code_execution_mode.py:126, GUIDE.md:120-125, ARCHITECTURE.md:94-106

Execution Diagnostics & IO Capturing

When code is executed within the sandbox, the _StreamProxy class in the generated entrypoint intercepts sys.stdout and sys.stderr, wrapping them in JSON frames before sending them to the host bridge.

IO Redirect Logic

The sandbox entrypoint rewires standard streams to prevent raw text from polluting the communication channel between the container and the bridge.

class _StreamProxy:
    def __init__(self, kind):
        self._kind = kind

    def write(self, data):
        if not data:
            return
        _send_message({"type": self._kind, "data": data})

sys.stdout = _StreamProxy("stdout")
sys.stderr = _StreamProxy("stderr")

Sources: mcp_server_code_execution_mode.py:726-742

Capturing Mechanism

• Stdout/Stderr: Captured as lists of strings in the CallToolResult.
• Noise Filtering: Benign noise (e.g., whitespace-only lines or () tokens) is filtered out to optimize context usage.
• MCP Client Stderr: PersistentMCPClient captures the stderr of proxied MCP servers into temporary files for diagnostic reporting during initialization failures.

Sources: mcp_server_code_execution_mode.py:270-282, mcp_server_code_execution_mode.py:534-540

Runtime & Lifecycle Diagnostics

The bridge performs "Lazy Runtime Detection," checking the health of the container runtime only when code execution is requested.

Runtime Health Checks

The RootlessContainerSandbox class manages runtime state and performs the following diagnostic checks:

1. Binary Discovery: Uses shutil.which to locate podman or docker.
2. Podman Machine Status: For Podman runtimes, the bridge probes podman machine info and attempts to auto-recover if the machine is stopped.
3. Volume Sharing Probes: Probes the Podman VM using podman machine ssh to verify if the state directory is correctly mounted.

Error Categorization

Diagnostic results are surfaced to the LLM and developers through specific error types and summary fields.

Status	Summary Pattern	Description
success	"Success" or "Success (no output)"	The code executed and exited with code 0.
timeout	"Timeout: execution exceeded {N}s"	The SandboxTimeout was triggered.
error	"Sandbox error: {exc}"	General sandbox failures (e.g., runtime missing).
validation_error	"Missing {param} argument"	Input parameters failed validation.

Sources: mcp_server_code_execution_mode.py:1267-1335, tests/test_entrypoint.py:80-95

Persistent Client Monitoring

The bridge maintains a PersistentMCPClient pool to avoid cold starts. Diagnostics for these clients include:

• Initialization Tracking: Monitoring the stdio handshake and reporting EOF or connection failures.
• JSON Parse Error Filtering: The bridge monkey-patches or filters out chatty MCP client noise (like blank lines) that would otherwise cause benign JSON parsing exceptions.
• Warm Session Monitoring: Tracking which servers are active and ready for proxying via runtime.list_loaded_server_metadata().

Sources: mcp_server_code_execution_mode.py:540-570, mcp_server_code_execution_mode.py:1225-1250, ARCHITECTURE.md:47-60

Summary

Logging and Diagnostics in this project are designed to bridge the gap between the host and an isolated sandbox. By wrapping standard IO in JSON frames and implementing robust runtime discovery, the bridge provides detailed diagnostic feedback—such as timeout durations and execution exit codes—while maintaining security boundaries. Future enhancements are planned to include structured logging with request IDs and metrics for container lifecycle events.

Sources: STATUS.md:45-55, ARCHITECTURE.md:120-125