MCP Lifecycle Management

Context manager and cleanup for MCP connections

MCP connections in PraisonAI Agents support context managers and explicit shutdown() so subprocesses, streams, and sockets close reliably.

MCP(...) accepts three equivalent construction forms — see Three equivalent forms.

from praisonaiagents import Agent, MCP

with MCP("uvx mcp-server-time") as mcp:
    agent = Agent(name="TimeAgent", instructions="Report the current time.", tools=mcp)
    agent.start("What time is it in UTC?")

The user runs an agent inside an MCP context manager; connections shut down cleanly when the session ends.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent, MCP
   
   with MCP("uvx mcp-server-time") as mcp:
       agent = Agent(
           name="TimeAgent",
           instructions="Get the current time",
           tools=mcp
       )
       print(agent.start("What time is it?"))
   # Connection closed automatically
   
2. With Configuration

   import os
   from praisonaiagents import Agent, MCP
   
   with MCP(
       command="npx",
       args=["-y", "@modelcontextprotocol/server-brave-search"],
       env={"BRAVE_API_KEY": os.getenv("BRAVE_API_KEY")},
       timeout=30
   ) as mcp:
       agent = Agent(name="SearchAgent", tools=mcp)
       agent.start("Search for Python tutorials")
   

How It Works

Phase	What happens
1. Enter	The with block opens the MCP connection
2. Use	The agent calls MCP-provided tools
3. Exit	shutdown() closes subprocesses, streams, and sockets

Agent-Managed Cleanup

When you pass an MCP client through the constructor (tools=[MCP(...)]), agent.close() and agent.aclose() now walk the agent’s tools and shut down anything exposing .shutdown() / .aclose() — so the MCP subprocess and its background thread are cleaned up with the agent.

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

agent = Agent(
    name="Coder",
    tools=[MCP("uvx some-mcp-server")],
    instructions="Use MCP tools",
)
try:
    agent.start("do work")
finally:
    agent.close()   # now correctly shuts down MCP subprocesses/threads
                    # (async: `await agent.aclose()`)

Constructor-pattern MCP clients (tools=[MCP(...)]) are now auto-shut-down by agent.close() / agent.aclose() — you don’t need remove_mcp_server() any more just for cleanup. aclose() prefers a tool’s aclose() and falls back to shutdown().

Manual Cleanup

For cases where a context manager is not suitable:

from praisonaiagents import MCP

mcp = MCP("uvx mcp-server-time")

try:
    tools = mcp.get_tools()
finally:
    mcp.shutdown()

Request Cancellation

An MCP client can abort an in-flight request by sending a notifications/cancelled notification naming the requestId it wants to stop.

1. Send the request

   The client calls a tool with a JSON-RPC id it can reference later.

   { "jsonrpc": "2.0", "id": 42, "method": "tools/call", "params": { "name": "search" } }
   
2. Cancel it

   The client sends a cancellation notification with the same id as requestId.

   { "jsonrpc": "2.0", "method": "notifications/cancelled", "params": { "requestId": 42 } }
   
3. Receive the cancelled response

   The server cancels the running task and replies with a JSON-RPC error.

   { "jsonrpc": "2.0", "id": 42, "error": { "code": -32603, "message": "Request cancelled" } }
   

Behaviour	What happens
Response	Cancelled id-bearing requests return -32603 "Request cancelled"; notifications receive nothing
Ordering	A cancel that arrives before the task is registered is stashed and applied immediately after registration
Overflow	Up to 10,000 pending cancel ids are kept in FIFO order — the oldest are evicted first, so a burst never drops the newest cancel

Only id-bearing requests can be cancelled. Fire-and-forget notifications have no id to reference and return nothing.

Lifecycle Methods

Authenticating the HTTP transport

When api_key is configured on the MCP HTTP-stream server, all of GET, POST, and DELETE require:

Authorization: Bearer <key>

Comparison uses constant-time hmac.compare_digest (timing-attack resistant). Missing or wrong tokens return 401 Unauthorized with {"error": "Unauthorized"}. DELETE returning 401 instead of 405 prevents information disclosure about whether sessions exist.

curl -H "Authorization: Bearer ${MCP_API_KEY:?Set MCP_API_KEY}" https://localhost:8080/mcp

__enter__ / __exit__

Context manager protocol for automatic resource management:

with MCP(command) as mcp:
    pass
# __exit__ calls shutdown() automatically

shutdown()

Explicitly close all connections and cleanup resources:

mcp = MCP("uvx mcp-server-time")
mcp.shutdown()

shutdown() dispatches to the right teardown call per transport. HTTP-stream and WebSocket clients expose close() (not shutdown()), so shutdown() falls back to close() for them — previously these two transports leaked on shutdown.

Transport	Client method actually invoked
Stdio	subprocess terminate + stream close
SSE	HTTP stream close
HTTP Stream	close() (fallback)
WebSocket	close() (fallback)

Since PraisonAI #4423, a failed construction (handshake timeout or init error) invokes an internal MCPToolRunner.stop() — a best-effort teardown that joins the background thread so a failed handshake does not leak a stdio subprocess. It runs automatically inside MCP.__init__; it is not a public API. Public shutdown stays mcp.shutdown() or the context-manager form. See MCP → Errors on construction.

__del__

Destructor ensures cleanup even if shutdown() was not called:

mcp = MCP("uvx mcp-server-time")
del mcp  # __del__ calls shutdown()

Connection Types

MCP supports multiple connection types, all with proper cleanup:

# Stdio
with MCP("uvx mcp-server-time") as mcp: ...

# SSE
with MCP("http://localhost:8080/sse") as mcp: ...

# HTTP Stream — pass the full endpoint URL your server exposes (e.g. /mcp)
with MCP("http://localhost:8080/mcp") as mcp: ...

# WebSocket
with MCP("ws://localhost:8080") as mcp: ...

All four transports now close uniformly on shutdown(). HTTP-stream and WebSocket close via the close() fallback inside MCP.shutdown() — previously these two leaked subprocesses/threads on shutdown, while stdio and SSE cleaned up correctly.

Best Practices

Always use a context manager

Prefer with MCP(...) as mcp: — cleanup runs even when an exception is raised.

Handle exceptions inside the block

Wrap tool calls in try/except inside the with block; __exit__ still closes the connection.

Nest multiple MCP instances carefully

Open each MCP in its own with block or nest them — both instances shut down in reverse order.

Pass secrets via env, not inline

Use the env= parameter with os.getenv(...) rather than hard-coding API keys in recipe files.

Related

MCP CLI

Run and inspect MCP servers from the terminal

MCP Transports

Stdio, SSE, HTTP stream, and WebSocket options

Agent Lifecycle Cleanup

How agent.close() shuts down MCP tools and breakers