Skip to content

Session Manager

The MCPClientSessionManager simplifies managing MCP (Model Context Protocol) client sessions by enabling on-demand session creation. Unlike the traditional approach where you open a session at startup and keep it alive, MCPClientSessionManager allows you to open sessions only when needed inside tool functions or agent workflows with automatic resource cleanup.

Author: Priyanshu Deshmukh

When to Use MCPClientSessionManager#

Use MCPClientSessionManager when you need:

  • Multi-server workflows — Connect to multiple MCP servers (arXiv, Wikipedia, APIs) in a single agent workflow
  • Dynamic server selection — Let agents choose which server to use based on the query context
  • Resource efficiency — Avoid keeping connections open when not in use
  • Mixed transport types — Work with both local stdio servers and remote SSE endpoints
  • Tool-based architecture — Integrate MCP servers as tools that agents invoke on-demand

For single-server, long-running workflows where you maintain one persistent connection, use the standard MCP Clients approach instead.

Installation#

Install AG2 with MCP support:

pip install ag2[openai,mcp]

Key Components#

StdioConfig#

Configuration for stdio-based MCP servers (local processes). Communicates via stdin/stdout.

from autogen.mcp.mcp_client import StdioConfig

arxiv_server = StdioConfig(
    command="python3",
    args=["mcp/mcp_arxiv.py", "stdio", "--storage-path", "/tmp/arxiv_papers"],
    transport="stdio",
    server_name="ArxivServer",
)

SseConfig#

Configuration for SSE-based MCP servers (HTTP endpoints). Connects via Server-Sent Events.

from autogen.mcp.mcp_client import SseConfig

wikipedia_server = SseConfig(
    url="http://127.0.0.1:8000/sse",
    timeout=10,
    sse_read_timeout=60,
    server_name="WikipediaServer",
)

MCPConfig#

Container for multiple server configurations. Enables dynamic server selection at runtime.

from autogen.mcp.mcp_client import MCPConfig, StdioConfig, SseConfig

mcp_config = MCPConfig(
    servers=[arxiv_server, wikipedia_server]
)

Basic Usage#

Open a session within an async context manager. The session is automatically initialized and cleaned up on exit:

from autogen.mcp.mcp_client import MCPClientSessionManager, StdioConfig, create_toolkit

arxiv_server = StdioConfig(
    command="python3",
    args=["mcp/mcp_arxiv.py", "stdio", "--storage-path", "/tmp/arxiv_papers"],
    transport="stdio",
    server_name="ArxivServer",
)

async with MCPClientSessionManager().open_session(arxiv_server) as session:
    tools = await session.list_tools()
    toolkit = await create_toolkit(session=session)
    # Use the toolkit with your agent...

Tool-Based Integration#

A powerful pattern is wrapping MCPClientSessionManager in a tool function, allowing agents to dynamically choose which MCP server to use:

from autogen.mcp.mcp_client import (
    MCPClientSessionManager,
    MCPConfig,
    StdioConfig,
    SseConfig,
    create_toolkit,
)
from autogen import ConversableAgent, LLMConfig
from autogen.tools import Tool

# Configure multiple servers
mcp_config = MCPConfig(
    servers=[
        StdioConfig(
            command="python3",
            args=["mcp_arxiv.py", "stdio", "--storage-path", "/tmp/arxiv"],
            transport="stdio",
            server_name="ArxivServer",
        ),
        SseConfig(
            url="http://127.0.0.1:8000/sse",
            server_name="WikipediaServer",
        ),
    ]
)

async def query_mcp_server(server_name: str, query: str) -> str:
    """Query an MCP server by name. Use ArxivServer for papers, WikipediaServer for articles."""
    server = next(s for s in mcp_config.servers if s.server_name == server_name)
    async with MCPClientSessionManager().open_session(server) as session:
        toolkit = await create_toolkit(session=session)
        # Use toolkit.tools to execute based on query...
        return "Result from MCP server"

# Register the tool with your agent
agent = ConversableAgent(
    name="researcher",
    llm_config=LLMConfig(config_list={"model": "gpt-4o", "api_type": "openai"}),
)
agent.register_for_llm(description="Query MCP servers: ArxivServer or WikipediaServer")(query_mcp_server)

The agent can now decide at runtime which server to call based on the user's request.

Use Cases#

Use cases: (1) Building a research assistant that queries arXiv for papers and Wikipedia for articles in a single conversation; (2) Routing user queries to different data sources (database, API, file system) via multiple MCP servers; (3) Running one-off operations against servers without maintaining persistent connections.