MCP Tools Server

Agency Swarm supports serving your tools as production-ready MCP (Model Context Protocol) endpoints. This enables AI models to interact with your tools remotely over HTTP, making them accessible to any MCP-compatible client or AI system.

Setting Up MCP Server

To expose tools as a standalone MCP endpoint, use the run_mcp() function from the integrations module. This will create an MCP server that will serve provided tools over the streamable HTTP protocol.

Example: Serving Individual Tools

from agency_swarm import function_tool, run_mcp
from pydantic import BaseModel, Field

class InputArgs(BaseModel):
    input_field: str = Field(..., description="Test input for the tool")

@function_tool
async def echo_function(args: InputArgs) -> str:
    """Returns a unique id"""
    return f"Tool called with input: {args.input_field}"

# Start MCP server with individual tools.
# This will setup a streamable-http server by default on port 8000
run_mcp(tools=[echo_function])

Configuration Options

The run_mcp() function accepts several configuration parameters:

run_mcp(
    tools=[ExampleTool, TestTool],  # List of Function tools or BaseTools
    host="0.0.0.0",                 # Host to bind server to
    port=8000,                      # Port to bind server to
    app_token_env="APP_TOKEN",      # Environment variable for auth token
    server_name="mcp-tools-server", # MCP server identifier
    return_app=False,               # Return app instead of running server
    transport="streamable-http"     # Preferred mcp protocol to use
)

Authentication

Authentication is controlled via environment variables:

import os
os.environ["APP_TOKEN"] = "your-secret-token"  # Or set in .env file

If no APP_TOKEN is set, authentication will be disabled and the server will accept all requests.

MCP Client Usage

Local MCP Server
Hosted MCP Server

This example shows how to use a local MCP server with stdio transport:

import asyncio
from agents.mcp.server import MCPServerStdio, MCPServerStdioParams
from agency_swarm import Agency, Agent

# Set up local MCP server using stdio transport
stdio_server = MCPServerStdio(
    MCPServerStdioParams(
        command="python", # or "npx" if available
        # Path to your MCP server script or npx arguments
        args=["./path/to/your/mcp_server.py"]
    ),
    cache_tools_list=True
)

# Create agent with local MCP server
mcp_agent = Agent(
    name="LocalMCPAgent",
    mcp_servers=[stdio_server],
)

agency = Agency(mcp_agent)

async def run_local_example():
    await stdio_server.connect()
    response = await agency.get_response("List all mcp tools")
    print(response.final_output)
    await stdio_server.cleanup()

if __name__ == "__main__":
    asyncio.run(run_local_example())

This example shows how to connect to a hosted MCP server over HTTP:

import os
import asyncio
from agency_swarm import Agency, Agent, HostedMCPTool

# Create agent with hosted MCP server
mcp_agent = Agent(
    name="HostedMCPAgent",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "mcp-tools-server",
                # Update with your hosted MCP server URL
                "server_url": "https://your-server.com/mcp/",
                "require_approval": "never",
                "headers": {
                    "Authorization": (
                        f"Bearer {os.getenv('APP_TOKEN', 'your-token')}"
                    )
                }
            }
        ),
    ],
)

agency = Agency(mcp_agent)

async def run_hosted_example():
    # HostedMCPTools do not require manual connection
    response = await agency.get_response("List all mcp tools")
    print(response.final_output)

if __name__ == "__main__":
    asyncio.run(run_hosted_example())

For hosted MCP servers, ensure your server is accessible from the internet. You can use tools like ngrok for local development.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Setting Up MCP Server

Example: Serving Individual Tools

Configuration Options

Authentication

MCP Client Usage

See Also

​Setting Up MCP Server

​Example: Serving Individual Tools

​Configuration Options

​Authentication

​MCP Client Usage

​See Also

Setting Up MCP Server

Example: Serving Individual Tools

Configuration Options

Authentication

MCP Client Usage

See Also