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

Agency Swarm provides helpers to connect to the three common MCP transport protocols. Choose the server type based on how your tool provider operates:

MCPServerStdio: For Command-Line Tools

MCPServerSse: For Web Service Tools

MCPServerStreamableHttp: For HTTP Streaming Tools

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 during initialization. Agency Swarm then automatically discovers the tools offered by the server and makes them available to the agent under the name you specified (e.g., Filesystem_Server.list_files). Follow these steps:

Step 1: Define Stdio Server Connection (e.g., Filesystem)

This example shows how to configure MCPServerStdio to run the standard MCP filesystem tool using npx.

from agency_swarm.tools.mcp import MCPServerStdio

filesystem_server = MCPServerStdio(
    # This name determines how the agent accesses the tools (e.g., Filesystem_Server.list_files)
    name="Filesystem_Server",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."], # Run in current directory
    },
    # cache_tools_list and strict are direct arguments for Stdio
    cache_tools_list=False,
    strict=False,

    # You can restrict the agent to using specific tools from the server by providing allowed_tools list
    allowed_tools = ["tool_1_name", "tool_2_name"]
)

Step 2: Define SSE Server Connection (Optional)

This example shows how to configure MCPServerSse to connect to a hypothetical web server running locally that provides tools via SSE.

from agency_swarm.tools.mcp import MCPServerSse

# Assumes your SSE server is running at this URL
sse_server = MCPServerSse(
    name="My_Custom_SSE_Server", # Tools will be accessed like My_Custom_SSE_Server.some_tool
    params={
        "url": "http://localhost:8080/sse",
    },
    cache_tools_list=False,
    strict=False,

    # Not providing allowed_tools will attach all available tools to the agent
)

Step 3: Define Streamable HTTP Server Connection (Optional)

This example shows how to configure MCPServerStreamableHttp to connect to a web server that implements the Streamable HTTP transport protocol.

from agency_swarm.tools.mcp import MCPServerStreamableHttp, MCPToolParams

read_file_tool = MCPToolParams(
    name="read_file", 
    description="Read the contents of a file", 
    # Schema can also be a pydantic's BaseModel
    schema={
        "type": "object", 
        "properties": {
            "filename": {
                "type": "string",
                "description": "The path to the file to read"
            }
        }, 
        "required": ["filename"]
    }
)

# Assumes your Streamable HTTP server is running at this URL
streamable_server = MCPServerStreamableHttp(
    name="My_Streamable_Server", # Tools will be accessed like My_Streamable_Server.tool_name
    params={
        "url": "http://localhost:7860/mcp",  # The MCP endpoint that handles both POST and GET
    },
    cache_tools_list=False,
    strict=False,

    # Use pre_loaded_tools if you want to avoid pulling tool list on every server initialization
    # Warning: when using this parameter, tool selection will be limited to a list of pre-loaded tools
    # and no tool validation will be performed, make sure provided tools match the expected server schema
    pre_loaded_tools=[read_file_tool]
)

Step 4: Initialize Agent with Servers

Pass the list of configured server connections to the mcp_servers parameter when creating your Agent.

from agency_swarm import Agent

# Assuming filesystem_server, sse_server, and streamable_server are defined as above
my_mcp_agent = Agent(
    name="MCPAgent",
    description="An agent that can use filesystem, SSE, and Streamable HTTP tools.",
    instructions="Use the Filesystem_Server tools to manage files, My_Custom_SSE_Server tools for custom tasks, or My_Streamable_Server tools for web-based operations.",
    # Pass the list of configured servers here
    mcp_servers=[filesystem_server, sse_server, streamable_server],
    temperature=0,
)

# Agency Swarm automatically discovers tools from the connected servers.
# Example: my_mcp_agent.tools will now include tools like
# 'Filesystem_Server.read_file', 'My_Custom_SSE_Server.get_data', 'My_Streamable_Server.read_file', etc.

Runnable Demo

For a practical, runnable example using both MCPServerStdio and MCPServerSse, see the demo_mcp.py script located in the tests/demos/ directory of the Agency Swarm repository.

Remember: The demo requires you to run the example SSE server (sse_server.py) in a separate terminal first.

Key Takeaways

MCP connects agents to external tools/data via standard protocols (Stdio, SSE, Streamable HTTP).
Use MCPServerStdio for command-line tool servers, MCPServerSse for SSE-based web servers, and MCPServerStreamableHttp for HTTP streaming servers.
Define server connections using the appropriate class, providing name, params, and optionally configuring strict and cache_tools_list.
Pass configured server instances to the Agent’s mcp_servers parameter during initialization.
The name you give a server connection becomes the prefix for its tools (e.g., MyServerName.tool_name).
External MCP servers (especially SSE and streaming HTTP ones) 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