AsyncMCPConsole
A persistent, callable connection to mcp-console serve.
Usage
AsyncMCPConsole(*, command=None, args=None, server_parameters=None)Enter and close the connection in the same async task. The application owns its model clients, agents, and tool loops. The context starts the server and discovers its tools; leaving the context closes its connection and process. Variables persist across send() calls to the same named session. A new connection starts with a fresh default session. By default the client prefers Console in the current Python environment, then PATH, and launches serve. Use command and args to select another executable or launch configuration.
Parameters
command: Command | None = None-
Console executable. Defaults to the installed
mcp-console. args: Sequence[Command] | None = None-
Server arguments. Defaults to
["serve"]. server_parameters: Mapping[str, Any] | None = None-
MCP stdio settings such as
cwdandenv.
Examples
Install with pip install 'mcp-console[client]'. This script defines values in one cell and uses them in a second cell:
import asyncio
from mcp_console import AsyncMCPConsole
async def main():
async with AsyncMCPConsole() as console:
print(
await console.send(
python="values = [12, 15, 18, 20, 25]; values"
)
)
print(
await console.send(
python="import statistics; statistics.mean(values)"
)
)
asyncio.run(main())Framework adapters are created inside this context, after discovery. See Anthropic, chatlas, Responses, or Agents.
Attributes
| Name | Description |
|---|---|
| tools | All MCP tool definitions discovered when this connection opened. |
tools
All MCP tool definitions discovered when this connection opened.
tools: ‘list[Tool]’
Discovery includes every page and does not require a send tool. Use plural framework adapters to register every discovered schema. Recreate adapters after reconnecting to pick up changed definitions.
Methods
| Name | Description |
|---|---|
| connect() | Start MCP Console and initialize its MCP client session. |
| close() | Close the MCP client session and terminate its subprocess. |
| get_tool() | Return a discovered definition, or raise if the name is absent. |
| call_tool() | Call a discovered tool by name and return its complete MCP result. |
| send() | Run or control the persistent R, Python, and SQL console. |
| __aenter__() | |
| __aexit__() |
connect()
Start MCP Console and initialize its MCP client session.
Usage
connect()
close()
Close the MCP client session and terminate its subprocess.
Usage
close()
get_tool()
Return a discovered definition, or raise if the name is absent.
Usage
get_tool(name)
call_tool()
Call a discovered tool by name and return its complete MCP result.
Usage
call_tool(name, arguments)Arguments are forwarded unchanged, including explicit null values. The result preserves content blocks, structured content, and is_error. This method does not require a tool named send.
send()
Run or control the persistent R, Python, and SQL console.
Usage
send(
*,
r=None,
python=None,
sql=None,
note=None,
session=None,
control=None,
requirements=None,
stdin=None,
timeout_ms=None
)Send at most one of r, python, or sql per call. If result.text ends in [running; poll with an empty send], call again with the same session and without code or stdin until completion before submitting another cell to that session. Different sessions can run concurrently. An empty call without session polls all active sessions and lists their statuses. console(...) is an alias for send(...). If tool configuration hides timeout_ms, poll without that argument.
Parameters
r: str | None = None-
One complete R cell.
python: str | None = None-
One complete Python cell.
sql: str | None = None-
One complete SQL cell on the selected connection.
note: str | None = None-
Plain text or Markdown journal entry. May accompany code or be sent alone without polling or consuming output.
session: str | None = None-
Session name. Code, input, and notes use “default” when omitted. A new name starts an independent session on its first code call. Omission or None on an empty poll collects all active sessions; pass “default” to poll only that session.
control: Literal["interrupt", "restart"] | None = None-
Interrupt the active operation or restart the runtime.
requirements: Requirements | None = None-
Declaration keyed by r, python, or duckdb, with optional python_version and exclude_newer constraints. action defaults to add; get normally returns inspection data in
structured_content, but can return a startup notice before the runtime is ready; set replaces omitted fields with empty values; reset restores startup defaults. Changed replacements of a live worker require control=“restart”. stdin: str | None = None-
Exact input for an active prompt or debugger.
timeout_ms: int | None = None- Maximum observation wait; timeout does not cancel work. Omission or None uses the server default of 60,000 ms.
Returns
ConsoleResult-
A
ConsoleResultretaining the complete MCP response. Itstextproperty contains text output and lifecycle notices;
imagesholdsnative image blocks, and
contentpreserves their order. Printingthe result renders image placeholders; notebook display renders
the images. Callingsend()itself does not display anything.
Raises
ConsoleError-
An MCP tool error, with the complete response available as
error.result. This is aRuntimeErrorsubclass.
Examples
A short observation window may return before the cell finishes. Poll with an empty call, collecting each chunk without rerunning the cell:
import asyncio
from mcp_console import AsyncMCPConsole
async def main():
async with AsyncMCPConsole() as console:
output = await console.send(
python="sum(range(1_000_000))",
timeout_ms=0,
)
print(output, end="")
while output.text.endswith("[running; poll with an empty send]"):
output = await console.send(session="default")
print(output, end="")
asyncio.run(main())
__aenter__()
Usage
__aenter__()
__aexit__()
Usage
__aexit__(exc_type, exc, traceback)