MCP Integration

Agency Swarm agents can interact with a wider range of tools and data sources beyond their built-in capabilities by using the Model Context Protocol (MCP). MCP is an open standard (view specification) that allows agents to communicate with external services like local file systems, databases, or custom APIs, as long as those services implement the protocol. Think of MCP as a universal translator that lets your agent talk to specialized external tools.

Why use MCP?

Access Local Resources: Let agents read/write local files or run local commands.
Connect to Custom Services: Integrate with proprietary APIs or internal tools without writing specific Agency Swarm tool wrappers for each one, provided an MCP server exists.
Leverage Existing MCP Tools: Utilize third-party tools that already support MCP.

Supported MCP Server Types

In v1.x, Agency Swarm provides helpers to connect to MCP servers using the Agents SDK. Choose the server type based on how your tool provider operates:

MCPServerStdio: For Command-Line Tools

Use this if your tool server is a command-line program or script. Agency Swarm will start this program for you and communicate with it directly using its standard input/output.

When to use: Your tool is a local script, an executable, or requires running a specific command to be activated.

from agents.mcp.server import MCPServerStdio, MCPServerStdioParams

stdio_server = MCPServerStdio(
    MCPServerStdioParams(
        command="python", # or 'npx' if available
        args=["./path/to/your/mcp_server.py"]
    ),
    cache_tools_list=True
)

MCPServerSse: For Web Service Tools

Use this if your tool server is already running as a web service at a specific HTTP URL. Agency Swarm connects to this URL to access tools exposed via Server-Sent Events (SSE).

When to use: Your tool is provided by a web API, a microservice, or any server accessible via an HTTP endpoint that speaks MCP+SSE.

from agents.mcp.server import MCPServerSse, MCPServerSseParams

sse_server = MCPServerSse(
    MCPServerSseParams(
        url="http://localhost:8000/sse/",
        headers={
            "Authorization": "Bearer secret-token"
        }
    )
)

MCPServerStreamableHttp: For HTTP Streaming Tools

Use this if your tool server is a web service that implements the Streamable HTTP transport protocol. This uses HTTP POST requests with optional Server-Sent Events (SSE) streaming for responses.

When to use: Your tool server operates as an independent web service, supports multiple client connections, needs stateful or stateless operation, or requires server-to-client streaming capabilities.

from agents.mcp.server import MCPServerStreamableHttp, MCPServerStreamableHttpParams

streamable_http_server = MCPServerStreamableHttp(
    MCPServerStreamableHttpParams(
        url="http://localhost:8000/mcp/",
        headers={
            "Authorization": "Bearer secret-token"
        }
    )
)

HostedMCPTool: For Public Web Servers

Use this if your tool server is a publicly accessible web service. This approach uses OpenAI’s hosted MCP tool capabilities.

When to use: Your tool server is accessible from the internet and you want to leverage OpenAI’s infrastructure for MCP connections.

from agency_swarm import HostedMCPTool

hosted_tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "mcp-tools-server",
        # For http servers:
        "server_url": "https://your-server.com/mcp/",
        # For sse servers
        # "server_url": "https://your-server.com/sse/",
        "require_approval": "never",
        "headers": {
            "Authorization": f"Bearer secret-token"
        }
    }
)

Server specified in the HostedMCPTool should be publicly accessible for the agent to be able to use this tool

Connecting Agents to MCP Servers

To give an agent access to MCP tools, you define the server connections and pass them to the agent’s mcp_servers list or tools list during initialization. Follow these steps:

Step 1: Define Local Server Connections

Configure local MCP servers (stdio, local SSE, or streamable HTTP) that will run on your machine.

from agents.mcp.server import MCPServerStdio, MCPServerStdioParams

# Example: Stdio server for local tools
stdio_server = MCPServerStdio(
    MCPServerStdioParams(
        command="python",
        args=["./examples/utils/stdio_mcp_server.py"]
    ),
    cache_tools_list=True
)

Step 2: Define Hosted Server Tools (Optional)

Configure hosted MCP tools for publicly accessible servers.

from agency_swarm import HostedMCPTool

hosted_tool = HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "mcp-tools-server",
        "server_url": "https://your-public-server.com/mcp/",
        "require_approval": "never",
        "headers": {
            "Authorization": f"Bearer {os.getenv('APP_TOKEN', 'your-token')}"
        }
    }
)

Step 3: Initialize Agent with Servers

Pass the configured server connections to the appropriate parameter when creating your Agent.

from agency_swarm import Agent

# For local MCP servers, use mcp_servers parameter
local_agent = Agent(
    name="LocalMCPAgent",
    description="An agent that can use local MCP tools.",
    instructions="Use the available MCP tools to help users.",
    mcp_servers=[stdio_server],  # Local servers go here
    model="gpt-4.1",
)

# For hosted MCP servers, use tools parameter
hosted_agent = Agent(
    name="HostedMCPAgent",
    description="An agent that can use hosted MCP tools.",
    instructions="Use the available hosted MCP tools to help users.",
    tools=[hosted_tool],  # Hosted tools go here
    model="gpt-4.1",
)

Runnable Demo

For a practical, runnable example using both local and hosted MCP servers, see the complete example above or the mcp_server_example.py script located in the examples/ directory of the Agency Swarm repository.

Remember: The demo requires you exposing port 8000 through ngrok prior to running it.

Key Takeaways

MCP connects agents to external tools/data via standard protocols (Stdio, SSE, Streamable HTTP).
v1.x: Use mcp_server for local mcp servers and HostedMCPTool for web-based servers, since the latter allows you to avoid maintaining server lifecycle.
v0.x: Use MCPServerStdio for command-line tools, MCPServerSse for SSE servers, and MCPServerStreamableHttp for HTTP streaming servers.
External MCP servers must be running separately for the agent to connect to them.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Why use MCP?

Supported MCP Server Types

Connecting Agents to MCP Servers

Runnable Demo

Key Takeaways

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

​Why use MCP?

​Supported MCP Server Types

​Connecting Agents to MCP Servers

​Runnable Demo

​Key Takeaways

Why use MCP?

Supported MCP Server Types

Connecting Agents to MCP Servers

Runnable Demo

Key Takeaways