> ## Documentation Index
> Fetch the complete documentation index at: https://agency-swarm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect your agents to external tools and data using the Model Context Protocol (MCP).

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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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/)