MCPServerManager is an async context manager in the OpenAI Agents SDK that orchestrates a pool of MCP (Model Context Protocol) servers, handling concurrent connection setup and per-server task affinity during cleanup. It accepts timeout, failure-handling, and parallelism options: failures can be strict (halt immediately) or lenient (record and continue), and connections run serially or in parallel while preserves cleanup ordering per server. MCP (Model Context Protocol) is a standard interface through which an AI agent communicates with external tool servers by invoking callable tools each server exposes.
MCPServerManager in src/agents/mcp/manager.py is an async context manager that calls connect_all() on __aenter__ and cleanup_all() on __aexit__.[1] During construction, MCPServerManager deduplicates the server list so the same server object cannot appear twice in all_servers.[1]
MCPServerManager defaults to connect_timeout_seconds=10.0 and cleanup_timeout_seconds=10.0; both accept a positive finite number of seconds or None to disable the timeout.[1] A value of zero is rejected because it would create an immediate deadline — only positive finite numbers or None are accepted.[1] Timeout validation runs on both construction and property assignment, so assigning an invalid value after construction also raises.[1]
When drop_failed_servers=True (the default), MCPServerManager.active_servers excludes servers that failed to connect; when False, failed servers remain in active_servers.[1] When strict=True, MCPServerManager raises on the first connection failure; when False (the default), failures are recorded in failed_servers/errors and the run proceeds with the remaining servers.[1] Setting connect_in_parallel=True spawns a dedicated _ServerWorker task per server so connects run concurrently while preserving the task affinity required for cleanup.[1]
MCPServerManager.active_servers and related properties return snapshots (new lists/dicts), so callers do not hold live references to internal state.[1] _ServerWorker in src/agents/mcp/manager.py serializes all connect and cleanup commands through an asyncio.Queue, ensuring per-server operations are ordered and run in the same task.[1] _ServerWorker.cleanup in src/agents/mcp/manager.py is idempotent: a second call reuses the existing _cleanup_future rather than enqueuing another cleanup command.[1] _run_with_timeout_in_task in src/agents/mcp/manager.py uses asyncio.timeout (Python ≥ 3.11) when available, and falls back to a loop.call_later cancel handle on older Python to preserve task affinity for MCP server cleanup.[1]
Canonical usage of MCPServerManager in src/agents/mcp/manager.py as an async context manager, passing active_servers to an Agent:
async with MCPServerManager([server_a, server_b]) as manager:
agent = Agent(
name="Assistant",
instructions="...",
mcp_servers=manager.active_servers,
)
MCPServerManager in src/agents/mcp/manager.py can be used in a FastAPI lifespan to share managed MCP servers across requests:
@asynccontextmanager
async def lifespan(app: FastAPI):
async with MCPServerManager([server_a, server_b]) as manager:
app.state.mcp_manager = manager
yield
app = FastAPI(lifespan=lifespan)
Sources