Output Formats

Relevant source files

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

• mcp_server_code_execution_mode.py
• tests/test_toon_responses.py
• README.md
• GUIDE.md
• ARCHITECTURE.md
• STATUS.md
• HISTORY.md

The MCP Server Code Execution Mode bridge provides structured and configurable output formats to communicate the results of Python code execution within the sandbox back to the Model Context Protocol (MCP) client. The system primarily supports two distinct rendering modes—Compact (the default) and TOON—which balance human readability, token efficiency for LLMs, and machine-parsable structure.

Every execution result is returned as a CallToolResult object. This object contains a mirrored structuredContent payload for programmatic access and a TextContent list for the primary textual response. The bridge employs filtering logic to strip "noise" (such as blank lines or empty data structures) to minimize context usage during agent interactions.

Sources: mcp_server_code_execution_mode.py:126-128, README.md:162-167, STATUS.md:21-23

Core Output Logic

The bridge processes internal SandboxResult data into a standard response payload before rendering it according to the configured mode. This process involves splitting raw output into lines, filtering out noise tokens (like () empty tuple artifacts), and omitting empty fields.

The diagram shows the transformation of raw sandbox output into a filtered, structured result based on the environment configuration.
Sources: mcp_server_code_execution_mode.py:273-316, mcp_server_code_execution_mode.py:348-379

Shared Response Payload

Regardless of the textual rendering, the internal structured data contains specific fields derived from the execution.

Field	Description
status	Execution status (e.g., "success", "error", "timeout", "validation_error").
summary	A brief textual summary of the result.
exitCode	The process exit code (omitted if 0 or None).
stdout	A list of strings representing the filtered standard output.
stderr	A list of strings representing the filtered standard error.
servers	A list of MCP servers loaded for the execution.
error	The specific error message if the execution failed.
timeoutSeconds	The configured timeout limit if a timeout occurred.

Sources: mcp_server_code_execution_mode.py:382-414, GUIDE.md:65-72

Output Modes

Compact Mode (Default)

Compact mode is designed for maximum token efficiency. It renders output as plain text, preserving stdout and stderr content exactly as emitted while trimming empty fields from the structuredContent payload. This ensures that system prompts remain lean without losing critical context.

• Logic: It joins filtered output lines and prepends status/exit information only if they deviate from a successful result.
• Structured Content: Contains a minimal payload, often omitting status if it is "success" and exitCode if it is 0.

Sources: mcp_server_code_execution_mode.py:319-345, README.md:163-164, GUIDE.md:175-177

TOON Mode

TOON mode utilizes Token-Oriented Object Notation to provide rich, deterministic blocks. This mode is activated by setting the environment variable MCP_BRIDGE_OUTPUT_MODE=toon.

• Block Formatting: The text content is wrapped in a markdown code block tagged as ```toon.
• Fallback: If the toon_format library is unavailable, the bridge automatically falls back to a pretty-printed JSON block within ```json.
• Usage: Preferred for scenarios requiring rich structure or deterministic tokenization for downstream LLM prompts.

Sources: mcp_server_code_execution_mode.py:284-301, README.md:165-167, tests/test_toon_responses.py:26-38

Error and Timeout Handling

Output formats explicitly handle failure states to ensure agents can diagnose issues. In both modes, if the execution exceeds the MCP_BRIDGE_MAX_TIMEOUT (default 120s) or MCP_BRIDGE_TIMEOUT (default 30s), the bridge surfaces partial output and specific error metadata.

Data Filtering logic

The bridge applies a filtering function to stdout and stderr to remove "noise tokens."

# mcp_server_code_execution_mode.py:273-281
_NOISE_STREAM_TOKENS = {"()"}

def _filter_stream_lines(lines: Sequence[str]) -> List[str]:
    """Drop whitespace-only or noise-only lines to save response tokens."""
    filtered: List[str] = []
    for line in lines:
        text = str(line)
        stripped = text.strip()
        if not stripped or stripped in _NOISE_STREAM_TOKENS:
            continue
        filtered.append(text)
    return filtered

Sources: mcp_server_code_execution_mode.py:126, mcp_server_code_execution_mode.py:273-281

Configuration Summary

The output behavior is primarily controlled via environment variables.

Variable	Default Value	Description
MCP_BRIDGE_OUTPUT_MODE	compact	Sets the rendering mode to either compact or toon.
MCP_BRIDGE_LOG_LEVEL	INFO	Adjusts the verbosity of bridge logging.

Sources: mcp_server_code_execution_mode.py:133-134, README.md:582-583, GUIDE.md:88-92

Conclusion

Output Formats in this bridge are optimized to reduce the "token bankruptcy" associated with traditional MCP servers. By utilizing the Compact format as a default, the bridge maintains a low context overhead, while the TOON mode offers an alternative for structured integration requirements. The automatic filtering of noise ensures that agents receive only high-value information from the sandboxed Python environment.

Sources: README.md:46-48, STATUS.md:21-23