Skip to content

Architecture

CodeExecutor coordinates three components: an IPython kernel for stateful execution of Python code and shell commands, a tool server for MCP tool dispatch, and an approval channel for application-level approval of tool calls and shell commands.

The application submits code to CodeExecutor, which forwards it to an IPython kernel running inside an optional sandbox. Inline shell commands use IPython's ! syntax1 and mix freely with Python code in a single block. When code calls a generated Python tool API function, the request routes to the tool server, which manages local (stdio) MCP servers and connections to remote (HTTP) MCP servers.

Before executing any tool call, the tool server sends an approval request back through CodeExecutor to the application, blocking until it accepts or rejects. Shell commands go through the same approval channel when shell command approval is enabled. MCP tool execution runs outside the kernel sandbox in the tool server. Shell commands execute as kernel subprocesses inside the sandbox when enabled.

mcpygen

The code generation and tool execution infrastructure is provided by mcpygen and re-exported by ipybox.

Architecture

CodeExecutor coordinates sandboxed execution of Python code and shell commands, MCP tool execution, and approval of tool calls and shell commands.

  1. %%bash/%%sh cell magics are also supported and run an entire code block as a shell script. ↩