MCPConsole
A synchronous, persistent connection to mcp-console serve.
Usage
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
cwdandenv.
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
connect()
close()
Close the MCP session, subprocess, and portal thread.
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, 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
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
__enter__()
__exit__()
Usage
__exit__(exc_type, exc, traceback)