MCP Session Management#

Overview#

MCP (Model Context Protocol) sessions in LangBot manage the full lifecycle of connections to external tool servers. Each server configuration is wrapped in a RuntimeMCPSession object, which handles transport initialization, tool discovery, tool invocation, health monitoring, and shutdown. All sessions are orchestrated by MCPLoader, which loads server configurations from the database at startup.

Key files:

• src/langbot/pkg/provider/tools/loaders/mcp.py — RuntimeMCPSession, MCPLoader
• src/langbot/pkg/provider/tools/loaders/mcp_stdio.py — BoxStdioSessionRuntime, MCPSessionErrorPhase, _ColdStartRetry

Session Lifecycle#

Each RuntimeMCPSession runs a single persistent background asyncio task — _lifecycle_loop_with_retry — that drives the full session state machine.

Startup#

start() launches the background lifecycle task and blocks on _ready_event.wait() with a configurable timeout (30 s for remote/SSE/HTTP; box_config.startup_timeout_sec + 30 for Box stdio) 1. The _ready_event (asyncio.Event) is set by _lifecycle_loop once the connection succeeds or all retries are exhausted, ensuring start() doesn't return until the session is in a terminal state.

States#

MCPSessionStatus has three values 2:

• CONNECTING — initial / mid-retry
• CONNECTED — healthy, tools available
• ERROR — all retries exhausted or non-retriable failure

Shutdown#

shutdown() sets _shutdown_event, then waits up to 5 s for the lifecycle task to exit cleanly. If the task times out, it is cancelled. The _lifecycle_loop finally-block calls exit_stack.aclose() and clears functions/resources/session 3.

Transport Modes#

_lifecycle_loop dispatches to a transport-specific initializer based on server_config['mode'] 4:

For remote mode, Streamable HTTP is tried first; if the server responds with HTTP 400, 404, or 405 (or the MCP SDK Session terminated sentinel mapped from 404), the transport is torn down and SSE is tried instead 7.

Retry Strategy with Exponential Backoff#

Fatal (non-transient) failures go through _lifecycle_loop_with_retry 8:

• Max retries: 3 (4 total attempts) — _MAX_RETRIES = 3 9
• Backoff delays: [2, 4, 8] seconds — _RETRY_DELAYS 10
• BOX_UNAVAILABLE short-circuit: this error phase bypasses all retries immediately, since retrying when Box is disabled is pointless 11

Two special exception types bypass the fatal retry budget entirely:

Both paths reset status to CONNECTING, clear error_message/error_phase, and call continue without incrementing attempt.

Concurrency: asyncio.Event Primitives#

Two asyncio.Event objects coordinate the session lifecycle 14:

• _ready_event — set once the session reaches CONNECTED or terminally ERROR. start() awaits this; any call to get_tools() / invoke_mcp_tool() before _ready_event is set will block or see session = None.
• _shutdown_event — set by shutdown(). Checked in _lifecycle_loop_with_retry before each retry; once set, no further retries or reconnects are attempted.

For Box stdio sessions, a second coroutine (monitor_process_health) runs concurrently with _shutdown_event.wait() using asyncio.wait(..., return_when=FIRST_COMPLETED) 15. When the monitor returns first, the lifecycle task checks whether the managed process is still running and raises either _TransportReconnect or a terminal exception accordingly.

Error Phase Tracking#

MCPSessionErrorPhase (defined in mcp_stdio.py) 16 tags which lifecycle stage failed, surfaced via get_runtime_info_dict() 17:

Known Limitation: No Tool-Call Timeout#

invoke_mcp_tool() calls await self.session.call_tool(tool_name, arguments) with no timeout wrapper. A slow or hung MCP server will cause the calling coroutine to block indefinitely. There is no per-call cancellation guard; the only protection is the startup timeout on _ready_event. Engineers adding new tool-call paths should wrap invoke_mcp_tool with asyncio.wait_for if they require bounded latency.

Transient vs. Persistent Sessions#

Sessions created from the admin "test" button carry no persisted UUID; the load_mcp_server method detects this, marks the config _transient=True, and generates a random UUID 18. Transient sessions are isolated from the shared Box session to prevent a failing test from churning healthy live connections 19.