---
title: 'MCP Integration'
description: 'Connect your agents to external tools and data using the Model Context Protocol (MCP).'
icon: "plug"
---

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](https://github.com/modelcontextprotocol/modelcontextprotocol)) 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 MCP servers using the Agents SDK. Choose the server type based on how your tool provider operates:

<Accordion title="MCPServerStdio: For Command-Line Tools" icon="terminal">
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.

```python
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
)
```
</Accordion>

<Accordion title="MCPServerSse: For Web Service Tools" icon="globe-pointer">
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.

```python
from agents.mcp.server import MCPServerSse, MCPServerSseParams

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

<Accordion title="MCPServerStreamableHttp: For HTTP Streaming Tools" icon="globe-pointer">
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.

```python
from agents.mcp.server import MCPServerStreamableHttp, MCPServerStreamableHttpParams

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

<Accordion title="HostedMCPTool: For Public Web Servers" icon="globe">
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.

```python
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"
        }
    }
)
```

<Note>
Server specified in the HostedMCPTool should be publicly accessible for the agent to be able to use this tool
</Note>
</Accordion>

## 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:

<Accordion title="Step 1: Define Local Server Connections">
Configure local MCP servers (stdio, local SSE, or streamable HTTP) that will run on your machine.

```python
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
)
```
</Accordion>

<Accordion title="Step 2: Define Hosted Server Tools (Optional)">
Configure hosted MCP tools for publicly accessible servers.

```python
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')}"
        }
    }
)
```
</Accordion>

<Accordion title="Step 3: Initialize Agent with Servers">
Pass the configured server connections to the appropriate parameter when creating your `Agent`.

```python
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-5.4-mini",
)

# 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-5.4-mini",
)
```
</Accordion>

<Note>
You can use `shared_mcp_servers` parameter inside agency to attach an MCP server to all agents at once.
</Note>

## 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).
*   Use mcp_server for local mcp servers and `HostedMCPTool` for web-based servers, since the latter allows you to avoid maintaining server lifecycle.
*   External MCP servers must be running separately for the agent to connect to them.

## See Also

- [Agents SDK MCP guide](https://openai.github.io/openai-agents-python/mcp/)