Swarms API Documentation - Build AI Agents & Multi-Agent Systems

The Swarms API supports Model Context Protocol (MCP) integration, allowing agents to connect to external servers and access additional tools, data sources, and capabilities beyond the base API.

MCP integration enables agents to access external databases, APIs, and tools through standardized server connections.

Quick Start

Python
JavaScript
cURL

import requests
import os

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "agent_config": {
        "agent_name": "Data Analyst with MCP",
        "description": "Data analyst with access to external databases",
        "system_prompt": "You are a data analyst with access to external data sources through MCP.",
        "model_name": "gpt-4.1",
        "max_tokens": 4096,
        "temperature": 0.5,
        "mcp_url": "https://github.com/mcp"  # Your MCP server URL
    },
    "task": "Query the customer database and provide insights on recent sales trends."
}

response = requests.post(
    f"{BASE_URL}/v1/agent/completions",
    headers=headers,
    json=payload
)

result = response.json()
print(result['outputs'])

const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";

const headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
};

const payload = {
    agent_config: {
        agent_name: "Financial Analyst",
        description: "Financial analyst with real-time market data access",
        system_prompt: "You are a financial analyst with access to real-time market data through MCP.",
        model_name: "gpt-4.1",
        max_tokens: 4096,
        temperature: 0.3,
        mcp_url: "https://your-mcp-server.com/financial-data"
    },
    task: "Analyze the current market trends for tech stocks and provide investment recommendations."
};

fetch(`${BASE_URL}/v1/agent/completions`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
    console.log("Analysis Results:", data.outputs);
    console.log("Token Usage:", data.usage);
})
.catch(error => console.error('Error:', error));

curl -X POST "https://api.swarms.world/v1/agent/completions" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "Data Analyst with MCP",
      "model_name": "gpt-4.1",
      "max_tokens": 4096,
      "temperature": 0.5,
      "mcp_url": "http://localhost:8001/sse"
    },
    "task": "Query the customer database and provide insights on recent sales trends."
  }'

MCP Server Setup

Local MCP Server

# Example MCP server setup (server.py)
from mcp import Server
import asyncio

app = Server("data-server")

@app.list_tools()
async def list_tools():
    return [
        {
            "name": "query_database",
            "description": "Query the customer database",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        }
    ]

@app.call_tool()
async def call_tool(name, arguments):
    if name == "query_database":
        # Your database query logic here
        return {"result": "Query executed successfully"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8001)

Running the MCP Server

# Install MCP dependencies
pip install mcp-server

# Run your MCP server
python server.py

Advanced MCP Configuration

Multiple MCP Connections

payload = {
    "agent_config": {
        "agent_name": "Multi-Source Analyst",
        "description": "Analyst with access to multiple data sources",
        "system_prompt": "You have access to multiple MCP servers for comprehensive analysis.",
        "model_name": "gpt-4.1",
        "max_tokens": 8192,
        "mcp_configs": {
            "connections": [
                {
                    "url": "http://localhost:8001/sse"
                },
                {
                    "url": "http://localhost:8002/sse"
                }
            ]
        }
    },
    "task": "Combine customer data with market trends to provide business insights."
}

Single MCP with Advanced Config

payload = {
    "agent_config": {
        "agent_name": "Advanced MCP Agent",
        "description": "Agent with advanced MCP configuration",
        "system_prompt": "You are connected to an MCP server with advanced capabilities.",
        "model_name": "gpt-4.1",
        "max_tokens": 4096,
        "mcp_config": {
            "url": "http://localhost:8001/sse",
            "timeout": 30,
            "authorization_token": "your-token",
            "transport": "streamable_http"
        }
    },
    "task": "Perform complex data analysis using the MCP server tools."
}

Use Cases

Database Integration

payload = {
    "agent_config": {
        "agent_name": "Database Analyst",
        "description": "SQL database integration specialist",
        "system_prompt": "You can query databases and analyze structured data.",
        "model_name": "gpt-4.1",
        "mcp_url": "http://localhost:8001/sse"
    },
    "task": "Analyze sales data from the past quarter and identify top performing products."
}

Financial Data Access

payload = {
    "agent_config": {
        "agent_name": "Financial Analyst",
        "description": "Real-time financial data analysis",
        "system_prompt": "You analyze financial markets and provide investment insights.",
        "model_name": "gpt-4.1",
        "mcp_url": "https://api.marketdata.com/mcp"
    },
    "task": "Analyze the current stock prices and provide buy/sell recommendations."
}

API Integration

payload = {
    "agent_config": {
        "agent_name": "API Integrator",
        "description": "External API integration specialist",
        "system_prompt": "You can call external APIs and integrate third-party services.",
        "model_name": "gpt-4.1",
        "mcp_url": "http://localhost:8003/sse"
    },
    "task": "Fetch weather data and provide travel recommendations based on current conditions."
}

Best Practices

Server Reliability: Ensure your MCP server is stable and handles errors gracefully
Authentication: Implement proper authentication for MCP server access
Timeout Handling: Set appropriate timeouts for long-running operations
Error Handling: Handle MCP connection failures and retry logic
Resource Management: Monitor resource usage and implement rate limiting
Documentation: Document available MCP tools and their capabilities

Cost Considerations

MCP Calls: $0.10 per request that sets mcp_url (charged once per request, not per tool call)
Token Usage: Additional tokens for MCP tool interactions
Server Costs: Costs associated with running your MCP server

Error Handling

try:
    response = requests.post(
        f"{BASE_URL}/v1/agent/completions",
        headers=headers,
        json=payload,
        timeout=60
    )

    if response.status_code == 200:
        result = response.json()
        print("MCP Results:", result['outputs'])
    else:
        print(f"MCP Error: {response.status_code} - {response.text}")

except requests.exceptions.Timeout:
    print("MCP request timed out")
except requests.exceptions.ConnectionError:
    print("Failed to connect to MCP server")
except Exception as e:
    print(f"MCP integration error: {e}")

Troubleshooting

Common Issues

Connection Refused: Ensure MCP server is running and accessible
Authentication Failed: Check API keys and authentication headers
Timeout Errors: Increase timeout values for complex operations
Tool Not Found: Verify tool names match server implementation
Rate Limiting: Implement backoff strategies for rate-limited endpoints

Debug Mode

Enable debug logging on your client to troubleshoot MCP issues:

import logging
logging.basicConfig(level=logging.DEBUG)

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

MCP Integration

Quick Start

MCP Server Setup

Local MCP Server

Running the MCP Server

Advanced MCP Configuration

Multiple MCP Connections

Single MCP with Advanced Config

Use Cases

Database Integration

Financial Data Access

API Integration

Best Practices

Cost Considerations

Error Handling

Troubleshooting

Common Issues

Debug Mode

​Quick Start

​MCP Server Setup

​Local MCP Server

​Running the MCP Server

​Advanced MCP Configuration

​Multiple MCP Connections

​Single MCP with Advanced Config

​Use Cases

​Database Integration

​Financial Data Access

​API Integration

​Best Practices

​Cost Considerations

​Error Handling

​Troubleshooting

​Common Issues

​Debug Mode

Quick Start

MCP Server Setup

Local MCP Server

Running the MCP Server

Advanced MCP Configuration

Multiple MCP Connections

Single MCP with Advanced Config

Use Cases

Database Integration

Financial Data Access

API Integration

Best Practices

Cost Considerations

Error Handling

Troubleshooting

Common Issues

Debug Mode