Build your own MCP server

Everything else in this section connects to somebody else’s server. This one is the other half: putting your functions behind MCP so any agent — or any MCP client, in any language, on any machine — can call them. The reason to do this rather than pass Python functions to Agent(tools=[...]) is process boundaries. A tool that needs a database credential, a GPU, or a private network can live where those things are, and agents reach it over HTTP.


Server framework	`MCPServer` from the `mcp` package (`FastMCP` on `mcp` 1.x)
Transport	streamable HTTP, `http://localhost:8000/mcp`
Model used here	`gpt-5.4-mini`

Prerequisites

pip install -U swarms "mcp>=2.0.0" requests
export OPENAI_API_KEY="sk-..."

mcp 2.x renamed FastMCP to MCPServer and moved it to mcp.server.mcpserver. On mcp 1.x, import from mcp.server.fastmcp import FastMCP instead; the decorator and run() call below are the same. The swarms client works with both.

Build it

Write the server

An MCPServer is a Python module with decorated functions. The decorator’s name and description are what the model sees, so write them for a reader who has no other context.

# crypto_price_server.py
import requests
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("CryptoPrice")


@mcp.tool(
    name="get_crypto_price",
    description="Get the current price and basic information for a given cryptocurrency.",
)
def get_crypto_price(coin_id: str) -> str:
    """
    Get the current price for a cryptocurrency using the CoinGecko API.

    Args:
        coin_id (str): The cryptocurrency ID (e.g. 'bitcoin', 'ethereum')

    Returns:
        str: A formatted string containing the cryptocurrency information
    """
    if not coin_id:
        return "Please provide a valid cryptocurrency ID"

    url = (
        "https://api.coingecko.com/api/v3/simple/price"
        f"?ids={coin_id}&vs_currencies=usd&include_24hr_change=true"
    )

    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()
    except requests.exceptions.RequestException as e:
        return f"Error fetching crypto data: {e}"

    if coin_id not in data:
        return f"Could not find data for {coin_id}. Please check the ID."

    price = data[coin_id]["usd"]
    change_24h = data[coin_id].get("usd_24h_change", "N/A")
    return f"Current price of {coin_id.capitalize()}: ${price:,.2f}\n24h Change: {change_24h:.2f}%"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Return a string, and make errors part of that string. An agent can reason about “Could not find data for bitcion”; it cannot reason about a traceback.

Run it

python crypto_price_server.py

It serves on http://127.0.0.1:8000/mcp. Leave it running.

Point an agent at it

In a second terminal:

from swarms import Agent

agent = Agent(
    agent_name="Crypto-Agent",
    agent_description="Answers cryptocurrency price questions.",
    model_name="gpt-5.4-mini",
    mcp_url="http://localhost:8000/mcp",
    max_loops=1,
)

print(agent.run("What is the current price of Bitcoin?"))

Identical to every hosted-server example in this section — only the URL differs.

Inspect the server without an agent

When a tool call misbehaves, take the model out of the loop. MCPManager is the class the agent uses internally:

from swarms.tools.mcp_manager import MCPManager

manager = MCPManager(mcp_url="http://localhost:8000/mcp")

print(manager.list_tool_names())                   # what the server exposes
print(manager.get_tools())                         # the schemas an LLM would see
print(manager.call_tool("get_crypto_price", {"coin_id": "bitcoin"}))

If call_tool returns what you expect and the agent still gets it wrong, the problem is the description or the prompt — not the server.

Tuning a connection to a local server

MCPConnection gives you per-server timeouts and headers:

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent",
    model_name="gpt-5.4-mini",
    mcp_config=MCPConnection(
        url="http://localhost:8000/mcp",
        name="local-tools",
        timeout=5,
        # headers={"Authorization": "Bearer ..."},
    ),
    max_loops=1,
)

MCP tools plus your own Python tools

The two coexist on one agent — MCP tools come from the server, and tools_list_dictionary (or tools=[...]) adds your own:

tools = [
    {
        "type": "function",
        "function": {
            "name": "add_numbers",
            "description": "Add two numbers together and return the result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "integer", "description": "The first number to add."},
                    "b": {"type": "integer", "description": "The second number to add."},
                },
                "required": ["a", "b"],
            },
        },
    }
]

agent = Agent(
    agent_name="Mixed-Tools-Agent",
    model_name="gpt-5.4-mini",
    tools_list_dictionary=tools,
    mcp_url="http://localhost:8000/mcp",
    max_loops=2,
)

An agent as a tool

To serve a swarms Agent, or a whole swarm, as an MCP tool, you do not need to write a server by hand. MCPDeployer wraps it, puts an auth layer in front, and serves it:

from swarms import Agent, MCPDeployer

analyst = Agent(
    agent_name="Market-Analyst",
    agent_description="Answers questions about markets and companies.",
    model_name="gpt-5.4-mini",
    max_loops=1,
    print_on=False,
)

if __name__ == "__main__":
    MCPDeployer(analyst, api_keys=["sk-local-dev"], port=8000).run()

That is how you compose swarms across process or machine boundaries: the calling agent does not know or care that the tool it invoked is itself an agent. See Serve an agent over MCP for the full walkthrough.

Writing tools an agent can use well

Rule	Why
One job per tool	The model picks by description; overlapping tools produce wrong picks.
Describe the arguments, with an example value	`coin_id` is ambiguous; “e.g. ‘bitcoin’, ‘ethereum’” is not.
Return strings, including for errors	The model can recover from a readable error; an exception reaches it only as `Error executing tool ...` with the exception text.
Keep outputs small	Every result is re-sent in the history on each later call of the run.
Name for search	With dynamic loading the name and description are what the search matches.

Sources: examples/mcp/servers/ and examples/mcp/client/

MCPManager API — the full client surface: async calls, multi-server routing, caching.
Model Context Protocol (MCP) — transports, OAuth, and error handling in depth.

Index

Basic Examples

Model Providers

Single Agent

Tree of Thoughts

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

Build your own MCP server

Prerequisites

Build it

Tuning a connection to a local server

MCP tools plus your own Python tools

An agent as a tool

Writing tools an agent can use well

Next

​Prerequisites

​Build it

​Tuning a connection to a local server

​MCP tools plus your own Python tools

​An agent as a tool

​Writing tools an agent can use well

​Next

Prerequisites

Build it

Tuning a connection to a local server

MCP tools plus your own Python tools

An agent as a tool

Writing tools an agent can use well

Next