Simplify multi-MCP server initialization

[aravind-segu]

Please read this first

• Have you read the docs?Agents SDK docs
• Have you searched for related issues? Others may have had similar requests

Describe the feature

Currently the UX around initializing multiple MCP Servers is a little cumbersome for the users. The CUJ mentioned in the docs would be as follows:

async with (
    MCPServerStreamableHttp(...) as mcp_server_a,
    MCPServerStreamableHttp(...) as mcp_server_b,
    MCPServerStreamableHttp(...) as mcp_server_c,
):
    agent = Agent(
        ...,
        mcp_servers=[
            mcp_server_a,
            mcp_server_b,
            mcp_server_c,
        ],
    )

    result = await Runner.run(agent, ...)

Some drawbacks of this can include:

• Verbose setup of multiple McpServers with async compared to Tools which can just be passed in as a list
• Handling the async lifecycle of each McpServer individually causes a tight coupling between MCP Server initialization, agent initialization and agent invocation
• Initializing Agent and running of the agent in the async clause can be cumbersome for Multi Agent usecases where agents can be defined in multiple different files

Some potential solutions for this can include:

1. Introducing a McpManger
   This manager can take in multiple mcp servers and manage a group connection of all MCP Servers, simplifying the code and also decoupling mcp server initialization, agent initialization and the invocation of the agent.

• Example CUJ from a previous ticket: How to properly invoke non-hosted MCP server in multi-agent workflow? #1881 (comment)
• Similar CUJ supported in langchain: https://github.com/langchain-ai/langchain-mcp-adapters?tab=readme-ov-file#client-1

2. Completely manage the lifecycle for the session connections
   To make the experience even simpler, the library can be updated to manage the async connections internally which can auto connect to the mcp session on startup and clean up the connections on exit or with an explicit close method.

agent = Agent(
    mcp_servers=[
        MCPServerStreamableHttp(...),
        MCPServerStreamableHttp(...),
    ]
)
result = await agent.run(...)

Would it be possible to introduce any of these?

[seratch]

Thanks for sharing this feedback. I understand your point. Let us think of possible enhancement in the long run.

For now, one quick solution might be to switch to hosted MCP server connections (if you don't use stdio or internal MCP servers): https://openai.github.io/openai-agents-python/mcp/#1-hosted-mcp-server-tools

[aravind-segu]

@seratch Yes the hosted mcp server tools would be a good alternative. However in our use case we want to run the server inside our own infrastructure, so we want to use the MCPServerStreamableHttp rather than a Hosted MCP Server

[seratch]

We're not yet commited to make any changes here, but I think something similar to the manager example at #1881 could be indeed conveninent for developers in terms of code simplicity. Also, the following approach should align with the current design too.

mcp_servers = AsyncMCPServers(
    servers=[
        MCPServerStreamableHttp(...)
        MCPServerStreamableHttp(...)
    ]
)
# when spinning your app up
await mcp_servers.connect_all()

agent = Agent(
    name="Assistant",
    instructions="Use the tools to answer the questions.",
    mcp_servers=mcp_servers,  # or mcp_servers.to_list()
)

# when terminating the whole app
await mcp_servers.cleanup_all()