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 on this connection. A new connection starts a new 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
send_tool The connected server’s MCP tool definition, used by SDK adapters.

send_tool

The connected server’s MCP tool definition, used by SDK adapters.

send_tool: Tool

Available after connecting. Its input schema reflects the server’s configured capabilities. Use a framework adapter to register this schema; automatic inference from send() annotations loses that detail. Recreate adapters after reconnecting.

Methods

Name Description
connect() Start MCP Console and initialize its MCP client session.
close() Close the MCP client session and terminate its subprocess.
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()

send()

Run or control the persistent R, Python, and SQL console.

Usage

Source

send(
    *,
    r=None,
    python=None,
    sql=None,
    control=None,
    requirements=None,
    stdin=None,
    timeout_ms=None
)

Send at most one of r, python, or sql per call. If output ends in [running; poll with an empty send], call again without code or stdin until completion before submitting another cell. 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.

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 JSON, 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

str

Collected text output and lifecycle notices. Images appear as MIME

placeholders. MCP tool errors raise RuntimeError.

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.endswith("[running; poll with an empty send]"):
            output = await console.send()
            print(output, end="")


asyncio.run(main())

__aenter__()

Usage

Source

__aenter__()

__aexit__()

Usage

Source

__aexit__(exc_type, exc, traceback)