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	`FastMCP` from the `mcp` package
Transport	streamable HTTP, `http://localhost:8000/mcp`
Model used here	`gpt-5.4-mini`

Prerequisites

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

Build it

Write the server

A FastMCP server 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.fastmcp import FastMCP

mcp = FastMCP("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://localhost: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

The most interesting server in the examples folder wraps a whole swarms Agent as a single MCP tool, so another agent — or any MCP client — can spawn and run it remotely:

from mcp.server.fastmcp import FastMCP
from swarms import Agent

mcp = FastMCP("MCPAgentTool")


@mcp.tool(
    name="create_agent",
    description="Create an agent with the specified name, system prompt, and model, then run a task.",
)
def create_agent(
    agent_name: str, system_prompt: str, model_name: str, task: str
) -> str:
    agent = Agent(
        agent_name=agent_name,
        system_prompt=system_prompt,
        model_name=model_name,
    )
    return agent.run(task)


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

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.

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 ends the call.
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

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