openai-agents-mcp

There are four ways to configure MCP settings in the Agents SDK:

1. Automatic Discovery (Recommended)

If you have mcp_agent.config.yaml and mcp_agent.secrets.yaml in your project directory, the SDK finds them automatically.

2. Explicit Config Path

Pass the path to your config file via RunnerContext.

from agents_mcp import RunnerContext

context = RunnerContext(mcp_config_path="/path/to/mcp_agent.config.yaml")

3. Programmatic Configuration

Define settings directly in code using MCPSettings and MCPServerSettings from mcp_agent.config.

from mcp_agent.config import MCPSettings, MCPServerSettings
from agents_mcp import RunnerContext

mcp_config = MCPSettings(
    servers={
        "fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),
        "filesystem": MCPServerSettings(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])
    }
)

context = RunnerContext(mcp_config=mcp_config)

4. Custom Server Registry

Use a custom ServerRegistry if you need specialized server management.

from mcp_agent.mcp_server_registry import ServerRegistry
from mcp_agent.config import get_settings
from agents_mcp import Agent

settings = get_settings("/path/to/config.yaml")
server_registry = ServerRegistry(config=settings)

agent = Agent(
    name="Custom Registry Agent",
    instructions="You have access to custom MCP servers.",
    mcp_servers=["fetch", "filesystem"],
    mcp_server_registry=server_registry
)

To stream responses from an agent instead of waiting for the full result, use Runner.run_streamed(). Note that this method is not awaited directly; instead, you iterate over the events in the returned stream.

from agents_mcp import Runner, ResponseTextDeltaEvent

# Use run_streamed (do not await the call itself)
result = Runner.run_streamed(
    agent,
    input="Print the first paragraph of https://openai.github.io/openai-agents-python/",
    context=context,
)

# Iterate through the stream events
async for event in result.stream_events():
    if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
        print(event.data.delta, end="", flush=True)

result = Runner.run_streamed(  # Note: No await here
    agent,
    input="Print the first paragraph of https://openai.github.io/openai-agents-python/",
    context=context,
)

# Stream the events
async for event in result.stream_events():
    if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
        print(event.data.delta, end="", flush=True)

The RunnerContext class is used with MCP-enabled Agents to manage Model Context Protocol (MCP) server configurations. It is designed to be compliant with the TContext generic parameter in the OpenAI Agent SDK.

You can initialize a RunnerContext in two ways:

1. Directly providing mcp_config: Pass an MCPSettings object containing your server configurations.
2. Providing a mcp_config_path: Pass the file path to your mcp_agent.config.yaml file.

Automatic Discovery: If both mcp_config and mcp_config_path are omitted, the context will attempt to find a file named mcp_agent.config.yaml by searching recursively upwards from the current working directory.

You can also pass arbitrary keyword arguments (**kwargs) to the constructor to attach additional custom attributes to the context instance.

from agents_mcp.context import RunnerContext

# Option 1: Using a config path
context = RunnerContext(mcp_config_path="./path/to/mcp_agent.config.yaml")

# Option 2: Using an MCPSettings object (if available)
# context = RunnerContext(mcp_config=my_mcp_settings)

# Option 3: Adding custom attributes
context = RunnerContext(mcp_config_path="mcp_agent.config.yaml", custom_id="agent-001")
print(context.custom_id)  # Output: agent-001

The as_tool() method allows you to wrap an Agent so it can be called as a tool by other agents.

Key Differences from Handoffs:

1. Input: Unlike handoffs (which pass conversation history), this tool receives generated input.
2. Control Flow: Unlike handoffs (where the new agent takes over), this tool is called as a standard tool, and the original agent continues the conversation after receiving the result.

Arguments:

• tool_name (str | None): The name of the tool. Defaults to the agent's name (transformed to function style).
• tool_description (str | None): A description of what the tool does.
• custom_output_extractor (Callable): A function to extract specific data from the RunResult. If omitted, the last message from the agent is used.

# Example of transforming an agent into a tool
agent_tool = agent.as_tool(
    tool_name="research_assistant",
    tool_description="Use this tool to perform deep research on a topic."
)

# The resulting 'agent_tool' can now be passed into the 'tools' list of another Agent
other_agent = Agent(name="Manager", tools=[agent_tool])