MCP server smolagents integration

ToolCallingAgent vs CodeAgent with MCP tools

smolagents provides two complementary agent architectures, each suited to different use cases:

Using MCPClient for auto-discovery

smolagents ≥ 1.9 ships with MCPClient, which calls tools/list on the server at startup and wraps each tool as a smolagents Tool object automatically:

import os
from smolagents import MCPClient, ToolCallingAgent, LiteLLMModel

# HTTP/SSE transport — production MCP servers
with MCPClient({
    "url": "https://search.internal/sse",
    "headers": {"Authorization": f"Bearer {os.environ['SEARCH_TOKEN']}"},
}) as mcp_client:
    tools = mcp_client.get_tools()  # auto-discovers all MCP tools

    model = LiteLLMModel(
        model_id="anthropic/claude-sonnet-4-6",
        api_key=os.environ["ANTHROPIC_API_KEY"],
    )
    agent = ToolCallingAgent(tools=tools, model=model, max_steps=15)
    result = agent.run("Find the three most-cited papers on MCP server security published in 2026.")
    print(result)

# Multiple MCP servers: combine tool lists
with (
    MCPClient({"url": os.environ["SEARCH_URL"], "headers": {"Authorization": f"Bearer {os.environ['SEARCH_TOKEN']}"}}) as search_client,
    MCPClient({"url": os.environ["DB_URL"],     "headers": {"Authorization": f"Bearer {os.environ['DB_TOKEN']}"}})     as db_client,
):
    tools = search_client.get_tools() + db_client.get_tools()
    agent = ToolCallingAgent(tools=tools, model=model)

The with MCPClient(...) as client context manager opens the connection, performs MCP initialization, and closes the connection cleanly on exit. All agent steps must occur inside the context — tool calls made after __exit__ will raise a ConnectionError.

Manual Tool subclass for custom wrapping

For cases where you need custom error handling, argument preprocessing, or response transformation beyond what MCPClient.get_tools() provides, subclass Tool directly:

from smolagents import Tool
from mcp import ClientSession
from mcp.client.sse import sse_client
import asyncio

class MCPSearchTool(Tool):
    name = "search_papers"
    description = (
        "Search academic papers on a topic. Returns a list of papers with titles, "
        "authors, abstracts, and URLs. Use when the user asks for research papers, "
        "scientific literature, or academic citations."
    )
    inputs = {
        "query": {
            "type": "string",
            "description": "Search terms or a natural language question about the topic",
        },
        "max_results": {
            "type": "integer",
            "description": "Maximum number of papers to return (default 10, max 50)",
            "nullable": True,
        },
    }
    output_type = "string"

    def __init__(self, session: ClientSession):
        super().__init__()
        self._session = session
        self._loop = asyncio.get_event_loop()

    def forward(self, query: str, max_results: int = 10) -> str:
        try:
            result = self._loop.run_until_complete(
                self._session.call_tool(
                    "search_papers",
                    arguments={"query": query, "max_results": max_results},
                )
            )
            if result.isError:
                return f"Search error: {result.content[0].text}. Try a more specific query."
            return result.content[0].text
        except Exception as e:
            # Return error string — never raise from forward()
            return f"MCP search unavailable: {type(e).__name__}: {e}. The server may be down."

smolagents' Tool.forward() is called synchronously. If your MCP session is async (which the Python MCP SDK requires), run the coroutine with asyncio.get_event_loop().run_until_complete() or use asyncio.run() if you are not already inside an event loop. For applications that are already async (FastAPI, async task queues), use await session.call_tool(...) directly by making forward async — smolagents supports async tools via async def forward in agent types that support async execution.

CodeAgent with MCP tools

In CodeAgent, the LLM writes Python code that calls tools as functions. smolagents injects each tool into the sandbox namespace using the tool's name attribute as the function name. MCP tools work identically to any other smolagents tool in this context:

from smolagents import CodeAgent, LiteLLMModel, MCPClient

with MCPClient({"url": os.environ["DATA_MCP_URL"], ...}) as client:
    tools = client.get_tools()
    model = LiteLLMModel("anthropic/claude-sonnet-4-6")

    agent = CodeAgent(
        tools=tools,
        model=model,
        additional_authorized_imports=["json", "re"],  # allow in sandbox
        max_steps=20,
    )

    # The LLM can write code like:
    # results = search_papers("MCP server security", max_results=20)
    # parsed = json.loads(results)
    # titles = [r["title"] for r in parsed if r["year"] == 2026]
    result = agent.run(
        "Find all MCP server security papers from 2026, extract their titles and "
        "citation counts, and return a ranked list sorted by citations descending."
    )

CodeAgent's Python sandbox approach is powerful for tasks that require iteration, filtering, or arithmetic over tool results — tasks that would require many sequential tool calls in a ToolCallingAgent become a single code block. The trade-off: the sandbox executes arbitrary LLM-generated Python, so restrict additional_authorized_imports to the minimum needed and run the agent in an isolated environment (Docker container, virtual machine, or smolagents' built-in LocalPythonExecutor with restricted builtins).

ManagedAgent for hierarchical MCP workflows

ManagedAgent wraps an agent as a tool callable by a parent orchestrator agent. This enables hierarchical workflows where different specialized agents each connect to their own MCP server:

from smolagents import ManagedAgent, ToolCallingAgent, LiteLLMModel, MCPClient

model = LiteLLMModel("anthropic/claude-sonnet-4-6")

# Specialist sub-agents, each with their own MCP connection
with (
    MCPClient({"url": os.environ["SEARCH_URL"], ...}) as search_client,
    MCPClient({"url": os.environ["CODE_URL"],   ...}) as code_client,
    MCPClient({"url": os.environ["DATA_URL"],   ...}) as data_client,
):
    search_agent = ToolCallingAgent(tools=search_client.get_tools(), model=model)
    code_agent   = ToolCallingAgent(tools=code_client.get_tools(),   model=model)
    data_agent   = ToolCallingAgent(tools=data_client.get_tools(),   model=model)

    # Wrap each specialist as a managed tool for the orchestrator
    managed_search = ManagedAgent(
        agent=search_agent,
        name="web_researcher",
        description="Researches current information on a topic using a live web search MCP server. "
                    "Call with a research question; returns a detailed research summary.",
    )
    managed_code = ManagedAgent(
        agent=code_agent,
        name="code_executor",
        description="Executes code analysis and transformation tasks using a code execution MCP server. "
                    "Call with a code task description; returns the execution result.",
    )
    managed_data = ManagedAgent(
        agent=data_agent,
        name="data_analyst",
        description="Queries and analyzes structured datasets using a database MCP server. "
                    "Call with a data question; returns a formatted analysis.",
    )

    orchestrator = ToolCallingAgent(
        tools=[managed_search, managed_code, managed_data],
        model=model,
        max_steps=10,
    )
    result = orchestrator.run(
        "Research the current state of MCP server adoption, analyse the registry data, "
        "and produce a summary report with statistics."
    )

The orchestrator sees web_researcher, code_executor, and data_analyst as tools — it calls them by name with a task description, and each managed agent runs its own ReAct loop using its dedicated MCP server. This isolation means a failure in the search MCP server only affects the web_researcher sub-agent; the data and code agents continue operating.

Monitoring MCP servers in smolagents pipelines

smolagents is commonly used for batch automation: scheduled pipelines, continuous data enrichment, on-demand research workflows triggered by external events. These pipelines can run for minutes or hours. An MCP server that goes down mid-pipeline produces error strings in tool results — the agent may loop, retry, or produce a partial answer without a clear failure signal to the calling system.

Combine a preflight check at pipeline start with AliveMCP continuous monitoring:

from smolagents import MCPClient

def verify_mcp_servers(server_configs: list[dict]) -> None:
    """Raise if any MCP server is unreachable before starting the pipeline."""
    for config in server_configs:
        try:
            with MCPClient(config) as client:
                tools = client.get_tools()
                if not tools:
                    raise RuntimeError(f"MCP server at {config['url']} returned no tools")
        except Exception as e:
            raise RuntimeError(
                f"MCP server preflight failed for {config.get('url', 'stdio')}: {e}\n"
                "Check server status at https://alivemcp.com"
            ) from e

# At pipeline entry point — fail fast before any LLM spend
verify_mcp_servers([
    {"url": os.environ["SEARCH_URL"], "headers": {"Authorization": f"Bearer {os.environ['SEARCH_TOKEN']}"}},
    {"url": os.environ["DB_URL"],     "headers": {"Authorization": f"Bearer {os.environ['DB_TOKEN']}"}},
])

The preflight opens a fresh connection, calls tools/list, verifies at least one tool exists, and closes the connection — all before the main pipeline starts. AliveMCP probes independently every 60 seconds, alerting you within a minute of any failure so you can investigate before the next pipeline run encounters a dead server.

Further reading

• MCP server LangChain integration — using MCP tools in LangChain agents
• MCP server Pydantic AI integration — type-safe agents with MCP
• MCP server error handling — isError, error codes, and retry patterns
• MCP server health check — designing a robust /health endpoint
• MCP server uptime monitoring — continuous availability checking
• AliveMCP — continuous protocol monitoring for MCP servers