MCP send reference
For clients that call Console or expose its tool to a model. To configure an existing MCP client, start with Get started.
Protocol compatibility
Console serves MCP over stdio using the official Rust SDK. It supports MCP 2026-07-28 and legacy clients that begin with initialize. Modern clients can begin with server/discover or call tools/list or tools/call directly, supplying the protocol version and client capabilities in each request’s _meta. Console includes its Implementation (name, title, version, description, and websiteUrl) in _meta["io.modelcontextprotocol/serverInfo"] on modern discovery, tool-list, and tool-call results, including tool errors. Legacy clients receive the same object as serverInfo in the initialize result; legacy tool results carry no identity. The identity is self-reported; clients may use it to attribute results or ignore it. Tool schemas use JSON Schema 2020-12.
The Python client uses the official Python SDK to discover the protocol and supply request metadata, including client identity. It prefers the modern protocol and retains the SDK’s compatibility path for legacy servers. The R client uses legacy initialization and declares its identity in initialize. Its ellmer tools attach the serverInfo from that handshake to successful results, under the same key modern results use. Console advertises tools; it does not advertise resources, prompts, sampling, or subscriptions.
Execution sessions are application state selected by the session tool argument. Every caller of a server process shares its session registry, including the literal default session; Console does not infer a conversation identity from requests. Clients sharing one server process should choose distinct session names for independent interpreter state. Modern clients should supply session on each session-specific call; omission retains Console’s default-session convenience. Named sessions share the process’s permission profile, as described below. Protocol discovery does not create or reset an execution session, and sessions do not survive a server restart.
MCP: send
One MCP connection owns a default session and any additional named sessions. Send at most one complete source cell per call. Collect its result before submitting another cell to that session. Different sessions can execute concurrently.
| Argument | Meaning |
|---|---|
r, python, sql |
Optional source string. At most one may be non-null. The configured language selection determines which fields are exposed. |
note |
Optional plain text or Markdown string annotating the recording; see Journal notes. |
session |
String selecting a session; defaults to "default". Omit it on an empty poll to collect all active sessions. |
timeout_ms |
Nonnegative integer; maximum observation wait, normally 60,000 milliseconds. It does not cancel execution. |
stdin |
Optional string of exact input bytes encoded as UTF-8. No newline is added. |
control |
interrupt or restart. |
requirements |
Dependency declaration or inspection action; see Requirements. |
Unknown fields and incorrect types are errors. Omit unused arguments. A hidden language field is rejected even when its value is null. session and timeout_ms cannot be null.
Examples are tool argument objects, not complete JSON-RPC messages:
{ "python": "values = [2, 4, 6]; sum(values)" }{ "sql": "SELECT 6 * 7 AS answer", "timeout_ms": 0 }Poll without source to collect more output; {} uses the default observation budget. Pass {"session":"default"} to poll only the default session. The operation rules below define admission, timing, and partial effects. For a walkthrough, see Drive send directly; for code execution and helpers, see Language behavior.
Named sessions
Supply a new name with code to start an independent session:
{ "session": "analysis", "python": "values = [2, 4, 6]; sum(values)" }Use the same name on later code, notes, input, requirements, and control calls. Each session owns its language objects, database connections, unread input, and accepted requirements. Sessions use the same launch configuration, working directory, and filesystem permissions; files in writable locations can be shared. There is no separate creation call. An unknown name on a poll does not start a worker. The optional sessions.max configuration limits live sessions, including default; the default is unlimited. Starting a new or stopped session at capacity returns an error without running its code.
An empty call, optionally with timeout_ms, collects output from all active sessions. Stopped sessions are omitted unless they have undelivered output or an error. When only one session is included, the result uses the ordinary single-session format. Otherwise, output sections are sorted by session name, and each starts with the session name and status. Status is starting, running, waiting_for_stdin, idle, or stopped. Poll results carry text and images in content and omit structuredContent. A targeted poll of a stopped session returns [stopped]. Supplying session polls only that session and preserves the ordinary single-session result format.
To release a named session’s worker, send {"session":"analysis","control":"restart"} without code or nonempty stdin. It stays stopped until a later code or nonempty-input call starts it again. After worker cleanup, it no longer counts toward sessions.max. Worker failure also leaves a named session stopped; polling never restarts it or replays failed code. The default session retains automatic recovery and immediate explicit restart. Closing the MCP connection stops all its sessions.
Results
MCP results contain text and, when produced, images. Language exceptions normally appear as console text; preparation, transport, and worker failures are tool errors. Errors do not undo earlier side effects.
| Notice | Action |
|---|---|
[running; poll with an empty send] |
Poll without code. Do not resubmit the cell. |
[waiting for stdin] |
Supply stdin, usually with a trailing newline. |
[worker starting] |
Startup is pending. Poll; do not assume interpreters are ready. |
[done] |
The operation completed without additional display content, or a combined control-and-cell call finished. |
[idle] |
No evaluation is active. Startup hooks or later idle callbacks can still produce output. |
[stopped] |
The selected session has no worker. Send code or nonempty stdin to start it. |
[prepared] |
Standalone dependency preparation succeeded. |
Notices may be accompanied by output, elapsed time, preparation phases, or diagnostics. A notice within output starts on its own line, including when an earlier poll returned a partial line. Console output that a ready worker wrote before starting a cell precedes [output produced while idle] and the cell’s output, even when it arrives after the cell was admitted. Output that an earlier response already returned stays where it was returned. Native standard-stream writes, for example from C code or subprocesses, travel separately and may land on either side of the marker near the cell boundary. Treat the text as user-visible status rather than an independently versioned machine-state protocol. The client packages do not turn it into a structured job API.
Text previews are bounded and can omit output. Recording reference explains retained logs and their limits. Requirements inspection is different: its complete declaration is available in MCP structuredContent, even when the text preview is shortened.
Output limits
| Output | Limit |
|---|---|
| Text in one complete response, including notices | 8 KiB of UTF-8 text |
| Images per undrained interval and complete result | 8 MiB of encoded data, 64 KiB of MIME metadata, and 4,096 images |
| SQL preview | 20 rows and 12 columns; the response text budget still applies |
Images are admitted whole, not partially returned. These response limits are independent of raw image capture; recordings can retain images omitted from a response. Omission notices identify retained logs or artifacts, and say when omitted content was not retained. Polling consumes the observed interval, including its omitted middle; use the named files rather than another poll to retrieve that text. Recording reference owns on-disk limits and failure behavior.
Calls and session lifetime
Cells and polling
{ "python": "answer = 6 * 7; answer" }If the response says [running; poll with an empty send], poll the same session without code to collect more output. Do not resubmit the source: the accepted cell continues and is not replayed. New code is rejected while a cell or its uncollected result is active in the selected session.
timeout_ms defaults to 60,000 and limits observation, not execution. 0 observes immediately. A targeted long poll such as {"session":"default","timeout_ms":300000} returns early on completion or managed input; it avoids repeated short polls. Omitting session polls all active sessions concurrently within one observation budget and can wait for other busy sessions.
Completion returns text/images, or [done] when empty. An idle poll returns pending idle output and [idle]. Elapsed/phase notices describe observations, not a queue position or completion guarantee.
Journal notes
Use note to record observations, questions, or the purpose of a step. It can accompany code, input, requirements, or a control operation without changing that operation. Console records the note without evaluating it and presents it before same-call code. See recorded notes and QMD rendering for association and rendering rules.
{ "note": "Check whether the missing values are confined to one batch." }A note-only call returns [done] without waiting for the runtime or collecting output from a running cell. Use session to associate a standalone note with a named session; omission selects default. Adding timeout_ms does not turn it into a poll; use an empty send to collect output. Omitting note or supplying null adds no annotation. The recording reference explains session association, retention, and failure behavior.
Server readiness
MCP initialization, tool discovery, and ping do not wait for runtime preparation. A valid early cell can be accepted while the shared startup continues. Its observation deadline includes startup; timeout does not cancel it or create another worker.
An empty poll or requirements inspection can return [worker starting]. Standalone requirements wait for shared startup and preparation, including initial discovery, without a timeout_ms deadline. Once transport is ready, [idle] does not necessarily mean every interpreter startup hook has finished.
After initial runtime discovery or preparation fails, fix the reported problem. The default session requires an explicit restart; a named session retries on its next code call or an explicit restart. Polls and input alone retain the failure until discovery succeeds. Rejected code and input are not replayed. If configured session startup code or native R initialization may already have run, an explicit restart is required before another attempt.
Standard input and managed reads
stdin queues exact UTF-8 bytes. It adds no newline, echoes nothing, and does not close the stream or acknowledge consumption. Line-oriented input normally needs \n:
{ "stdin": "yes\n" }R readline() / browser() and main-thread Python input() / pdb can report [waiting for stdin]. Answer with stdin, not another code cell. In R’s debugger, for example, c\n continues and Q\n quits.
Unread bytes can satisfy later reads and are discarded on restart. Direct fd-0 and descendant reads bypass managed-input notifications. Queue order does not determine which reader consumes the bytes.
Interruption
{ "control": "interrupt" }Interrupt signals the active resolver, otherwise the current worker. It does not start a missing worker or retarget a replacement. Interruption is cooperative: code can catch, delay, or block it. Use restart when fresh state is required.
On Windows, R-owned DuckDB supports native query interruption; long native Python-owned DuckDB queries can require restart.
A control-only interrupt may overlap a pending call. If that call owns polling or output delivery, interrupt returns a running notice without consuming its output. This does not permit concurrent cells within the selected session.
Explicit restart
{ "control": "restart" }Restart prepares changed requirements before retiring the old worker. Failed preparation preserves the old state. After retirement begins, replacement failure cannot restore live objects. Accepted requirements and recordings survive; language objects, database catalogs, and unread input do not.
A bundled cell or stdin reaches only the replacement after it is ready. For a named session, restart without a cell or nonempty stdin retires the worker without launching a replacement. The next code or nonempty-input call starts it with the retained requirements. Native R startup and configured session startup can run again and repeat side effects. No failed cell is automatically replayed.
Operations
Prefer separate calls for control, dependency changes, and execution unless bundling serves a clear purpose.
| Call | Effect order |
|---|---|
| Cell, with optional requirements/stdin | Validate and prepare requirements, then admit the cell and deliver input. |
| Requirements only | Validate and prepare; return [prepared]. Nonempty stdin is invalid. |
| Interrupt + cell | Deliver interrupt and input, allow interruption to settle, then prepare/admit the new cell only if prior work stopped. |
| Restart, with optional requirements/stdin/cell | Validate and prepare, commit requirements, retire; start the default session or a replacement receiving input/code. |
| Empty poll | Collect output from the selected session, or all active sessions when session is omitted; do not start a worker. |
| Stdin only | Queue input for the current generation and observe; after shared startup, it can start an initial/stopped worker. |
Requirements get |
Read the committed declaration without consuming output. |
Structural errors are rejected before actions. In the supported interrupt-plus-cell path, deferred requirement-content or policy errors occur after interrupt/input effects; those effects are not rolled back. Interrupt with requirements but no cell is invalid. Python-only sessions reject interrupt-plus-requirements entirely.
Changed set/reset normally needs explicit restart after user execution. A still-unused prewarmed worker has a limited replacement exception; configured session startup or nonempty user input ends it. See Requirements actions.
Wait timing and cancellation
The observation deadline starts at call entry. After startup, explicit preparation and control/retirement work can make the total call exceed it. Standalone package preparation, including initial discovery, has no timeout_ms deadline.
Cancelling a request’s wait after admission does not cancel the accepted cell or shared startup. Poll to discover retained state. Cancelling before admission leaves the cell unaccepted. Closing the MCP connection instead triggers owned cleanup.
Outputs are bounded and consumed by polling. Recovery after cancellation is not exactly-once client delivery: bytes can reach a client before cancellation settles. A recorded result proves assembly, not receipt. Developer details belong to Architecture.
Requirements
MCP argument objects, admission rules, and live package changes. For an introduction to package preparation, read Packages and environments. For startup declarations and policy settings, see Package settings. Accepted declarations are not installed-package inventories or lockfiles.
Inspecting and replacing requirements
The examples are MCP argument objects:
{ "requirements": { "action": "get" } }{ "requirements": { "python": ["requests[socks]>=2,<3"] } }{
"control": "restart",
"requirements": { "action": "set", "python": ["requests>=2"] }
}{ "control": "restart", "requirements": { "action": "reset" } }| Action | Meaning |
|---|---|
get |
Inspect the last committed declaration without consuming output or launching a worker. |
add (default) |
Accumulate requirements. Exact repeats do nothing. |
set |
Replace the complete declaration. Omitted lists and constraints are empty; no defaults are added. |
reset |
Restore the startup declaration captured from configuration, removing later additions. |
get may select session, but takes no code, control, stdin (even empty), or declaration fields. reset accepts no declaration fields. A bare requirements object {} is invalid; {"action":"set"} intentionally clears optional declarations.
Changed set or reset needs explicit restart while a live worker retains user code or nonempty input. A stopped named session can prepare a changed declaration, including set or reset, without launching a worker. An unused prewarmed worker can be replaced automatically after successful preparation. Unchanged requirements do not wait for bootstrap. When R is available, changed requirements wait for runtime bootstrap to finish; supply any requested startup input before changing requirements. Configured session startup code and failed/interrupted native R startup end that exception. An explicitly requested restart still occurs for unchanged requirements.
Inspection returns requirements, prepared, and runtime_requirements in structured content. requirements is the editable user declaration; runtime_requirements identifies additional runtime infrastructure. Skipped built-in defaults are absent from the accepted declaration. Plain restart retains that accepted declaration; reset retries the captured startup defaults under the configured resolution policies. During resolution, inspection reports the last commit, not an in-progress candidate. During initial startup it may instead return [worker starting].
Copy and edit the complete requirements object, then add action: "set" to replace it. Removing a declaration neither uninstalls a package nor prohibits its use; implicit resolution can add it again.
Accepted requirement input
| Field | Accepted values |
|---|---|
r |
Single-line ir package references, including supported remote references. Local sources, NUL, and line breaks are rejected. |
python |
Named PEP 508 registry requirements, with versions, extras, and markers. No paths, editable requirements, URLs, archives, or name @ URL references. |
duckdb |
Extension names of at most 64 characters: lowercase ASCII letter first, then lowercase letters, digits, or underscores. |
python_version |
A list of versions or supported ==, !=, <, <=, >, >= constraints, not executable paths. |
exclude_newer |
A publication cutoff accepted by uv, such as "2026-01-01", or null. |
Lists contain strings, not null. add accepts at most 64 entries per language per call; set accepts a complete accumulated manifest without that per-list limit.
add accumulates Python version constraints and can fill an unset cutoff, but cannot replace an existing cutoff. set clears omitted constraints and cutoffs. reset restores the configured baseline. Effective version-constraint changes on a live interpreter require restart.
Requirements for a cell
Requirements may accompany one cell or stand alone. Failed preparation withholds the accompanying cell. Standalone success returns [prepared]; standalone preparation rejects nonempty stdin. Its wait includes initial runtime discovery and is not limited by timeout_ms.
{
"requirements": { "python": ["polars>=1"] },
"python": "import polars as pl; pl.DataFrame({'value': [1, 2, 3]})"
}For ordinary calls, preparation precedes bundled input and code. Supported interrupt-plus-cell calls are different: the interrupt and input are delivered before deferred requirement validation. Those effects are not rolled back when the follow-up fails. Python-only sessions reject interrupt-plus-requirements combinations. See operation order.
Automatic R package resolution
Under implicit, a reached missing package load can request preparation through library(), require(), requireNamespace(), loadNamespace(), ::, or :::. Console does not scan source or rerun the cell.
Automatic requests accept plain package names. Use explicit requirements for remote references. Available packages, explicit lib.loc, and ordinary help/listing operations retain their native behavior. install.packages() is not intercepted.
Failure preserves the original loading operation’s behavior, including FALSE from a missing-package require() or requireNamespace(). A successfully accepted library remains available even if the subsequent load or cell fails.
Python declarations from R
For managed Python, evaluated reticulate::py_require() calls count as explicit dependency requests under explicit and implicit, including calls from R package .onLoad() hooks. Package extras, version constraints, and publication cutoffs retain their declared meaning.
reticulate::py_require("requests[socks]>=2.32,<3", python_version = ">=3.10,<4")
requests <- reticulate::import("requests")Before Python initializes, declarations remain local to the worker until preparation succeeds. They can be prepared on first Python use or together with a later MCP requirements request. Requirements inspection reports the last accepted declaration, including R-side requirements after successful preparation.
After initialization, compatible additions use live Python preparation and preserve live objects. Reticulate’s declaration checks still apply: changing existing package requirements, removing packages, changing the publication cutoff, or requesting an incompatible interpreter requires restart. Resolution failure preserves accepted requirements and live state. The fixed policy continues to reject changes; existing Python environments retain their native reticulate behavior.
Automatic Python import resolution
Managed Python defaults to explicit: declare dependencies through requirements.python or reticulate::py_require() before importing them. Set python.resolution: implicit in config.yaml to let a last-chance import finder prepare a missing distribution. Console registers this dependency-resolution finder only under implicit. Under explicit and fixed, missing imports retain native Python errors without distribution inference or a preparation request. Display, plotting, and reticulate interoperability hooks remain active independently of this policy. Existing standard-library, installed, local, and loaded modules retain normal lookup. Availability checks such as find_spec() do not install packages.
Known mappings include yaml → pyyaml, PIL → pillow, and sklearn → scikit-learn. Otherwise inference uses a conservative same-name fallback. It declines ambiguous shared namespaces, missing submodules of an available package, and absent standard-library modules. Missing optional imports during an installed package’s eager initialization retain ordinary behavior.
Use explicit requirements for the correct distribution, versions, extras, or markers. Preparation is available only on the configuring worker thread and process; prepare dependencies before starting background threads or fork children. Existing Python environments and bare workers do not use this finder.
An accepted environment survives a later import error. The cell is never replayed.
Live preparation
Changed additions require an idle worker, except automatic requests within the worker’s own execution. Preparation is noninteractive; finish managed input or debugger work first.
Live R preparation
Console changes its managed library entry while preserving other library paths and live objects. Loaded namespaces are not unloaded. Some activation failures leave recoverable state but require restart before further changes.
Live Python preparation
A compatible addition preserves objects and the running interpreter. It must match the loaded Python library and version and must not change a loaded distribution’s version. A new package can still change unloaded or transitive dependencies. Use restart for changes that need fresh imports or a different environment.
Live R and Python activations have separate acceptance points: a successful Python activation can remain after a later R failure. Arbitrary startup-hook effects are not rolled back.
DuckDB extension preparation
Preparation uses the selected engine’s installation and signature checks. An extension-only addition does not replace a SQL connection or catalog. A Python replacement that retains extension requirements must also supply a usable DuckDB provider; include duckdb explicitly when needed.
Restarting with requirements
Restart prepares and accepts changed requirements before retiring the old worker. A plain restart reuses accepted requirements without resolving again. Downloads, builds, and cache writes can remain after failed preparation; accepted declarations and filesystem effects have different lifetimes.
Resolution policy admission
The configured package policies apply independently to R and managed Python. Explicit requests include MCP add / set changes and managed Python declarations through reticulate::py_require(). Unchanged declarations remain no-ops; under fixed, reset can retry skipped startup defaults.
A mixed request is checked as a whole before preparation. set cannot omit a locked language to clear it, and reset or restart cannot unlock a policy. Changing a policy requires a new server connection. DuckDB extension preparation follows its managed provider’s policy; selecting another SQL connection does not grant preparation authority.
Client packages
The Python and R guides cover the client packages; Reference links their API documentation. Register tools through the supplied adapters so the model receives the connected server’s schema; inferring it from Python method annotations loses configured capabilities.
What is not a public compatibility contract
Hidden worker/relay/resolver subcommands, internal MCP_CONSOLE_* handoffs, process layouts, and recording journal schemas are implementation interfaces. Console-owned private protocols evolve in lockstep. The separately pinned native runner and external MCP protocol retain their own contracts.
Internal details belong in Architecture, Relay protocol, and Worker protocol. Open work is collected in TODO; it is not a list of promised APIs.