Skip to main content

MCPConsole

A synchronous, persistent connection to mcp-console serve.

Usage

Source

MCPConsole(*, command=None, args=None, server_parameters=None)

Use as a context manager or explicitly call connect() and close(). The context starts Console and discovers its tools; leaving it closes the connection and subprocess. Variables persist across calls to each named session. The application owns its model clients, agents, and tool loops. 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.

Calls block while the official MCP client runs on a background event loop. Connect and close only when no other call is in progress. Calls to different sessions can run concurrently from separate threads. A control-only interrupt may be sent from another thread while a call waits.

A KeyboardInterrupt during a response wait cancels that request’s wait, leaving an admitted cell running. The client waits for the SDK’s request cleanup before re-raising, so subsequent calls cannot overtake cancellation. Concurrent sends are rejected while cancellation cleanup is in progress; ordinary concurrent control calls remain available when a cell is running. The interrupted wait retains admission while publishing cancellation, so a competing send cannot pass between those steps.

Cleanup has a five-second limit; another KeyboardInterrupt also ends the wait. Cancellation submission does not wait for the SDK event loop, so the limit also applies while the SDK is busy validating a response. Interrupting before a request starts prevents it from being sent and leaves the connection usable.

If cleanup does not finish, the client aborts that request task and rejects further calls until the connection has been closed and reconnected. Closing waits at most five seconds for the aborted request to stop before closing the SDK transport and portal. If that request still cannot stop, closing raises an error and retains the invalid connection until it stops.

Catch KeyboardInterrupt inside the connection’s context to poll for output or call console.send(control="interrupt") to interrupt execution explicitly. Leaving the context closes the session. If SDK teardown raises after consuming its cleanup callbacks, the client records a disconnected state; reconnecting starts a fresh session.

Cancellation can race with delivery. A journaled result records response assembly, not confirmed client receipt.

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]'. Define values in one cell and use them in the next:

from mcp_console import MCPConsole

with MCPConsole() as console:
    print(console.send(python="values = [12, 15, 18, 20, 25]; values"))
    print(
        console.send(
            python="import statistics; statistics.mean(values)"
        )
    )

Create framework adapters inside this context, after discovery. See chatlas, Anthropic, 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. 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 session, subprocess, and portal thread.
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 a cell and return its complete ConsoleResult.
__enter__()
__exit__()

connect()

Start MCP Console and initialize its MCP client session.

Usage

Source

connect()

close()

Close the MCP session, subprocess, and portal thread.

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, content blocks, structured content, and is_error are preserved. Cancellation follows the same rules as send().

send()

Run or control a cell and return its complete ConsoleResult.

Usage

Source

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

The arguments and polling behavior match AsyncMCPConsole.send(). Send one language per call. If result.text ends in [running; poll with an empty send], collect the remaining output with console.send(session=...) before submitting another cell to that session. Omit session on an empty call to poll all active sessions and list their statuses. The result retains ordered text and images. print(result) renders image placeholders; IPython notebook display renders the images. send() does not display anything itself. MCP tool errors raise ConsoleError, a RuntimeError subclass retaining the complete response as error.result. console(...) is an alias for send(...). If tool configuration hides timeout_ms, poll without that argument.

__enter__()

Usage

Source

__enter__()

__exit__()

Usage

Source

__exit__(exc_type, exc, traceback)