MCP Console

MCP Console is an interactive, persistent computational workspace for agents. One MCP tool, send, provides R, Python, and SQL cells, plotting and image output, interactive input, dependency preparation, polling, interruption, and restart. Data, models, imports, and database state survive between calls, so an analysis can move between languages without starting over.

R, Python, and DuckDB are embedded in a single worker process. Python can access R variables through r.name, R can access Python objects through py$name, and SQL can query live R data frames. Data passes through in-process object bridges and conversions; NumPy can view R numeric arrays directly in memory. An agent can choose the language and libraries that fit each step without managing data transfers between separate runtime sessions.

Model-visible text is bounded to 8 KiB per response, with separate image limits. The server keeps recordings, plot artifacts, and raw cell output outside the model context; raw text retention is capped at 1 GiB per cell. A separate runtime process executes cells, with native sandboxing enabled by default and explicit ownership of startup, interruption, and cleanup.

Status

This is a development preview with changing interfaces. MCP Console supports macOS and Linux; Windows is unsupported. See the runtime limitations and sandbox lifetime limits.

The built-in worker requires R even for Python and SQL. It embeds R, uses reticulate for Python interoperability, and provides a persistent DuckDB connection for SQL. Python-only execution is not yet implemented.

Quickstart

Use an MCP client of your choice, such as Codex, Claude Code, or OpenCode.

You need uv and R on PATH. If you need R, install rig, then run rig add release.

Installing the current source also needs Git, rustup with Rust 1.95 or later, and your platform's build tools. On macOS, install the Xcode Command Line Tools with xcode-select --install. On Ubuntu, install the build dependencies with:

sudo apt-get update
sudo apt-get install -y build-essential git pkg-config libcap-dev libcurl4-openssl-dev binutils

Install the current checkout, including its private sandbox runner:

git clone --depth 1 https://github.com/t-kalinowski/mcp-console.git
cd mcp-console
uv tool install --python 3.12 --reinstall .

Configure your client to launch uvx mcp-console serve as a stdio server. For example, with Codex:

codex mcp add console -- uvx mcp-console serve
codex

Or with Claude Code:

claude mcp add --transport stdio console -- uvx mcp-console serve
claude

uv supplies Python 3.12, the first installation builds the pinned runner with its own Rust toolchain, and the first analysis prepares R and Python packages and DuckDB extensions. These steps can download interpreters, packages, and build dependencies and take several minutes. See source installation and managed dependencies for details.

Try an analysis

Check that your client exposes the console's send tool (/mcp in Codex), then ask:

Use MCP Console to tell me something interesting about the Palmer Penguins dataset. Load the data from the R package palmerpenguins, letting the console prepare any missing packages. Fit a small logistic regression in R to predict penguin sex from body measurements. Use SQL to summarize the live data by species, then use Python and Matplotlib to plot the data and the model's predictions. Explain what you found, keeping the data and model in the console for follow-up questions.

Follow up in the same conversation:

Using the model and data already in the console, where does the model make the most mistakes? Show me a plot and the path to the recorded console session transcript.

Records and plot artifacts are written under .agents/console/sessions/<run-id>/ in the server's working directory. Your client uses its configured model; the exact calls and responses can vary.

Reproducible reports

Each session produces a transcript.md with recorded calls and results, and a transcript.qmd containing the code as a Quarto document. Console automatically keeps the QMD front matter up to date with declared R and Python dependencies, including packages resolved dynamically during the session. Rendering with ir prepares those dependencies and reruns the code in a fresh R session, capturing new results and plots in HTML or another Quarto output format. This gives you a starting point for a reproducible report: copy the document to refine the analysis and add narrative. See the recording and rendering guide for commands and setup for SQL or remote sessions.

Architecture

The process diagram and ownership guide explain the boundaries:

• The server owns the session, operation admission, retained requirements, bounded responses, host dependency preparation, and recordings.
• The relay transports worker events, delivers signals, and shuts down and reaps its direct worker.
• The runtime worker owns live R, Python, and SQL state and evaluates one cell at a time.
• The private sandbox runner owns native enforcement, private temporary storage, and descendant supervision within its documented limits.

Restart discards in-memory language and database state while retaining prepared requirements in the server. Recordings remain files; they are not session checkpoints. The architecture separates host setup and recording from evaluated code, while the shared worker enables interoperation and means a restart affects all three languages.

SSH selects remote transport and execution while retaining local recordings. Docker adds an owned container; Docker Sandbox/SBX uses provider-managed microVM enforcement instead of the native runner. These targets have distinct prerequisites, policies, and cleanup contracts.

Limits and trust boundaries

Submitted code has shell-class capability. The default local native sandbox permits host-file reads, restricts direct networking, and denies regular-file writes outside private temporary storage. It does not protect sensitive files that the worker can read. Trusted project configuration can change this policy; there is no automatic unsandboxed fallback. Linux requires mounted /proc and permission for the native sandbox's namespace and policy operations; see host requirements. Restricted containers or host security policy may prevent startup.

Dependency preparation runs outside the worker sandbox and may execute trusted installation, build, or initialization code with host permissions. Use only trusted requirements and resolver configuration. See the dependency trust boundary.

There is one implicit session and cells run sequentially. Restart, worker replacement, and server exit discard live state. Recordings contain source, stdin, requirements, outputs, and artifacts without redaction, and have no aggregate retention quota or automatic cleanup. Retrieving omitted output requires filesystem access to the server's recording directory.

The generated Quarto document can include failed or rejected submissions. Review a copy before rendering; it executes code outside the worker sandbox.

Further reading

• Documentation index, runtime behavior, and send operation order.
• Python clients and integrations and the ellmer R package.
• Configuration, native sandbox policy, and dependency preparation.
• Development rules and source map, testing and snapshot updates, and build, packaging, and release procedures.

MCP Console grew out of mcp-repl. Documents under design-sketches/ describe exploratory future work, not current functionality. Licensed under the MIT license.