Serve an agent over MCP

Every other page in this section points an agent at an MCP server. This one makes an agent into one. Once it is served, any MCP client can call it as a tool: another Swarms agent, Claude Desktop, Cursor, or a script in another language.


Class	`MCPDeployer`
Transport	streamable HTTP, `http://127.0.0.1:8000/mcp`
Auth	one static API key
Model used here	`claude-sonnet-5`

Prerequisites

pip install -U swarms "mcp>=2.0.0"
export ANTHROPIC_API_KEY="sk-ant-..."

MCPDeployer needs mcp 2.0.0 or newer.

Build it

Write the server

The agent you want to share is an ordinary Agent. agent_description becomes the tool description the calling model reads, so write it for a reader with no other context.

server.py

from swarms import Agent, MCPDeployer

analyst = Agent(
    agent_name="Market-Analyst",
    agent_description="Answers questions about markets and companies in three sentences or fewer.",
    system_prompt="You are a concise market analyst. Answer in three sentences or fewer.",
    model_name="claude-sonnet-5",
    max_loops=1,
    print_on=False,
)

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

The tool is named after the agent: Market-Analyst becomes market_analyst.

Run it

python server.py

It prints a banner with the URL and keeps serving. Leave it running.

Check it from a second terminal

/health is public:

curl http://127.0.0.1:8000/health

{"status":"ok","name":"market_analyst","tool":"market_analyst","tools":["market_analyst"],"transport":"streamable-http"}

The MCP endpoint is not. A request with no key, or the wrong one, gets 401:

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8000/mcp
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "x-api-key: wrong" http://127.0.0.1:8000/mcp

401
401

Call it from another agent

The client is an ordinary agent too. MCPConnection carries the URL and the key.

client.py

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

manager = Agent(
    agent_name="Portfolio-Manager",
    system_prompt=(
        "You manage a portfolio. Use the market_analyst tool for any "
        "market question, then summarise its answer in one sentence."
    ),
    model_name="claude-sonnet-5",
    mcp_url=MCPConnection(
        url="http://127.0.0.1:8000/mcp",
        api_key="sk-local-dev",
    ),
    max_loops=2,
    print_on=False,
    output_type="final",
)

print(manager.run("What is the main risk to semiconductor stocks right now?"))

python client.py

The portfolio manager discovers market_analyst, calls it with the question as task, and summarises what the analyst returned. The server terminal logs each request.The client lists the server’s tools while it is being constructed, so start the server first. A server that is down, or a wrong key, makes the Agent(...) call itself raise AgentMCPConnectionError.

What just happened

MCPDeployer wrapped analyst as one MCP tool with the schema task: str, img: str | None.
Every request to /mcp went through the auth layer first. The key can arrive as x-api-key or as Authorization: Bearer, which is what MCPConnection sends.
The tool call ran analyst.run(task) on a worker thread and returned its answer as the tool result.

Other ways to connect a client

MCPConnection(url=..., api_key=...) sends Authorization: Bearer <key>, which the deployer accepts. These forms work too. The examples read the key from the environment, so export it first with export ANALYST_MCP_KEY="sk-local-dev". A URL string plus an agent-level key. mcp_api_key applies to every server that has no key of its own, and env: reads the key from the environment when the connection is made:

from swarms import Agent

manager = Agent(
    agent_name="Portfolio-Manager",
    model_name="gpt-5.4",
    mcp_url="http://127.0.0.1:8000/mcp",
    mcp_api_key="env:ANALYST_MCP_KEY",
    max_loops=2,
)

The x-api-key header, with a longer tool timeout. mcp_config takes a full MCPConnection. A swarms client waits tool_timeout seconds for one tool call, 120 by default, so raise it when the served agent or swarm is slow:

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

manager = Agent(
    agent_name="Portfolio-Manager",
    model_name="gpt-5.4",
    mcp_config=MCPConnection(
        url="http://127.0.0.1:8000/mcp",
        name="market-analyst",
        api_key="env:ANALYST_MCP_KEY",
        api_key_header="x-api-key",
        api_key_prefix=None,
        tool_timeout=300,
    ),
    max_loops=2,
)

Extra headers for custom auth. When the server uses an auth callable that reads other headers, such as a tenant id, send them with headers:

MCPConnection(
    url="http://127.0.0.1:8000/mcp",
    api_key="env:ACME_MCP_KEY",
    headers={"x-tenant": "acme"},
)

An SSE server. A deployer built with transport="sse" serves http://127.0.0.1:8000/sse. Clients default to streamable HTTP, so set the transport on the client too:

MCPConnection(url="http://127.0.0.1:8000/sse", api_key="sk-local-dev", transport="sse")

Variations

Keys from the environment instead of the code. api_key_env reads a comma-separated list, so you can rotate keys without a code change:

MCPDeployer(analyst, api_key_env="ANALYST_MCP_KEYS", port=8000).run()

Run the server inside your own script. start() and stop(), or a with block, run it on a background thread:

with MCPDeployer(analyst, api_keys=["sk-local-dev"], port=8000) as server:
    print(server.url)

Reachable from other machines. Bind to all interfaces and put TLS in front of it:

MCPDeployer(analyst, api_keys=["sk-prod-..."], host="0.0.0.0", port=8000).run()

Launched by an MCP host. Claude Desktop and similar hosts start servers as subprocesses over stdio. There are no HTTP headers on stdio, so the host itself is the security boundary. Stdout carries the protocol, so turn the banner off:

MCPDeployer(analyst, transport="stdio", allow_anonymous=True, show_banner=False).run()

A fresh agent per call. One served Agent handles every call and keeps its conversation between them. To give each call a clean history, serve a function that builds the agent. The function’s name and docstring become the tool’s name and description:

def market_analyst(task: str) -> str:
    """Answers questions about markets and companies in three sentences or fewer."""
    analyst = Agent(
        agent_name="Market-Analyst",
        system_prompt="You are a concise market analyst. Answer in three sentences or fewer.",
        model_name="gpt-5.4",
        max_loops=1,
        print_on=False,
    )
    return analyst.run(task)


MCPDeployer(market_analyst, api_keys=["sk-local-dev"], port=8000).run()

Troubleshooting

The client agent fails to build with AgentMCPConnectionError

The client could not list the server’s tools. Check that the server is running and the key matches. With mcp 2.x the client reports a rejected key as Server returned an error response rather than 401; the server log shows MCPDeployer rejected request to /mcp for each refused request.

The tool call fails after two minutes

That is the client’s tool_timeout, 120 seconds by default. Raise it on the MCPConnection, and set the server’s timeout to match if you use one.

A remote client cannot connect

The default host="127.0.0.1" only accepts local connections. Bind with host="0.0.0.0" and give clients the machine’s address, not 0.0.0.0.

Serve a team from one server

Several agents, a workflow, and a function, each its own tool.

MCPDeployer reference

Every parameter, auth mode, and method.

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

Serve an agent over MCP

Prerequisites

Build it

What just happened

Other ways to connect a client

Variations

Troubleshooting

Next

Serve a team from one server

MCPDeployer reference

​Prerequisites

​Build it

​What just happened

​Other ways to connect a client

​Variations

​Troubleshooting

​Next

Serve a team from one server

MCPDeployer reference

Prerequisites

Build it

What just happened

Other ways to connect a client

Variations

Troubleshooting

Next