Skip to main content

AsyncMCPConsole

A persistent, callable connection to mcp-console serve.

Usage

Source

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 cwd and env.

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

Source

connect()

close()

Close the MCP client session and terminate its subprocess.

Usage

Source

close()

get_tool()

Return a discovered definition, or raise if the name is absent.

Usage

Source

get_tool(name)

call_tool()

Call a discovered tool by name and return its complete MCP result.

Usage

Source

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

Source

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 ConsoleResult retaining the complete MCP response. Its text

property contains text output and lifecycle notices; images holds

native image blocks, and content preserves their order. Printing

the result renders image placeholders; notebook display renders

the images. Calling send() itself does not display anything.

Raises

ConsoleError
An MCP tool error, with the complete response available as error.result. This is a RuntimeError subclass.

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

Source

__aenter__()

__aexit__()

Usage

Source

__aexit__(exc_type, exc, traceback)