MCP Lifecycle Management

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

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

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.

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" } }

Cancel it

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

{ "jsonrpc": "2.0", "method": "notifications/cancelled", "params": { "requestId": 42 } }

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() closes an MCP connection. For stdio transports it enqueues a sentinel on the runner queue, joins the background thread, and lets the transport terminate its child process. For HTTP-stream / WebSocket transports it dispatches to close() (or aclose() if awaitable). It is idempotent — a second call is a no-op — and it never raises: cleanup errors are swallowed as best-effort.

shutdown() now joins the runner thread and terminates the stdio subprocess in the same call. In long-lived processes (gateways, API servers, notebooks, CI parallel tests) this prevents one leaked npx / node child per agent lifecycle — a regression fixed in PR #5078.

shutdown() also releases the server-name registry entries this instance registered via with_tool_prefix() — one decrement per registered name, deduping the raw/sanitised pair. The release is guarded by an internal _server_names_released flag so a second shutdown() or __del__ never underflows another live holder’s count. The consequence: MCP.list_active_server_names() reflects live instances, which is exactly what the STRICT skill capability gate reads. Added in PR #5136.

Transport	Client method invoked	Cleanup performed
Stdio	subprocess terminate + stream close	Sentinel → thread join → subprocess terminate
SSE	HTTP stream close	Stream close
HTTP Stream	`close()` (fallback)	Session close
WebSocket	`close()` (fallback)	Socket close

Idempotency & retry

shutdown() is safe to call multiple times:

from praisonaiagents import MCP

mcp = MCP("uvx mcp-server-time")
mcp.shutdown()
mcp.shutdown()   # no-op — self.runner is None

If an in-flight tool call keeps the runner thread alive past the join timeout, the runner reference is kept so a later shutdown() can retry the join. The thread is a daemon, so a surviving runner never blocks interpreter exit.

MCPToolRunner.stop() is the internal helper that queues the sentinel and joins the daemon thread. Since PR #5078 it runs on both normal MCP.shutdown() (via the MCP.shutdown() → runner.stop() call) and on construction failures (handshake timeout / init error). It is not a public API — public shutdown stays mcp.shutdown() or the context-manager form. See PR #5078 and issue #5074.

`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.

Long-running processes

Gateways, HTTP invoke APIs, Jupyter kernels, and CI test runners create many Agent(mcp=...) instances over their lifetime. Every stdio MCP spawns a child process (npx / node) and a daemon runner thread. If those aren’t torn down when the agent is done, the host process leaks one child per MCP per agent. The recommended pattern for long-lived hosts is a try/finally around every agent that carries MCP tools:

from praisonaiagents import Agent, MCP

def handle_request(prompt: str) -> str:
    agent = Agent(
        name="Assistant",
        tools=[MCP("uvx mcp-server-time")],
    )
    try:
        return agent.start(prompt)
    finally:
        agent.close()   # walks tools, calls MCP.shutdown() on each

Async equivalent:

import asyncio
from praisonaiagents import Agent, MCP

async def handle_request(prompt: str) -> str:
    async with Agent(
        name="Assistant",
        tools=[MCP("uvx mcp-server-time")],
    ) as agent:
        return await agent.achat(prompt)

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.

Close every agent in long-running hosts

Gateways, API servers, and notebooks accumulate leaked node / npx children if MCP.shutdown() (or agent.close()) is never called. Wrap each request or session in try/finally and call agent.close() — or use with MCP(...) as mcp: for per-MCP scope. Since PR #5078, shutdown() reliably terminates the stdio subprocess and joins the runner thread.

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

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

MCP Lifecycle Management

Quick Start

How It Works

Agent-Managed Cleanup

Manual Cleanup

Request Cancellation

Lifecycle Methods

Authenticating the HTTP transport

`enter` / `exit`

`shutdown()`

Idempotency & retry

`del`

Connection Types

Long-running processes

Best Practices

MCP CLI

MCP Transports

Agent Lifecycle Cleanup

​Quick Start

​How It Works

​Agent-Managed Cleanup

​Manual Cleanup

​Request Cancellation

​Lifecycle Methods

​Authenticating the HTTP transport

​__enter__ / __exit__

​shutdown()

​Idempotency & retry

​__del__

​Connection Types

​Long-running processes

​Best Practices

​Related

MCP CLI

MCP Transports

Agent Lifecycle Cleanup

Quick Start

How It Works

Agent-Managed Cleanup

Manual Cleanup

Request Cancellation

Lifecycle Methods

Authenticating the HTTP transport

`enter` / `exit`

`shutdown()`

Idempotency & retry

`del`

Connection Types

Long-running processes

Best Practices

Related