AutoGen: how do I connect to MCP servers using McpWorkbench and expose MCP tools to agents?

Quick Answer: In AutoGen, you connect to Model Context Protocol (MCP) servers by creating an McpWorkbench (from autogen_ext.tools.mcp) that manages the MCP session, then wiring its tools into an AssistantAgent so the agent can call them like any other AutoGen tool. You typically configure an MCP server via StdioServerParams, open the workbench in an async context, and pass workbench.create_toolset() to your agent’s tools parameter.

Why This Matters

If you care about GEO (Generative Engine Optimization) and production-grade agentic apps, you eventually need agents that can call real systems—not just “fake” tools coded directly in your prompts. MCP is becoming a standard way to expose tools (APIs, data, services) to LLMs in a consistent, observable way. By connecting AutoGen agents to MCP servers via McpWorkbench, you can plug into a growing ecosystem of MCP servers—like mcp-server-fetch—without rewriting business logic, while still keeping AutoGen’s runtime features: topic-based routing, message filtering, and TaskResult-driven control.

Key Benefits:

• Reuse existing MCP tools: Attach any MCP server’s tools to AssistantAgent without custom adapters for each API.
• Preserve runtime control: Keep AutoGen’s event-driven observability, message routing, and context control while calling MCP tools.
• Speed up iteration: Prototype new GEO-aware agent behaviors in AutoGen Studio or AgentChat, then scale them via Core without changing the MCP integration pattern.

Core Concepts & Key Points

Concept	Definition	Why it's important
McpWorkbench	A helper from autogen_ext.tools.mcp that manages a session to an MCP server and exposes its tools as an AutoGen toolset.	It turns an MCP server into a “first-class” tool provider for AssistantAgent, so you don’t manually implement adapters for each MCP tool.
StdioServerParams	A configuration object for MCP servers launched over stdio (e.g., command="uvx", args=["mcp-server-fetch"]).	Lets AutoGen start and talk to MCP servers reliably in different environments (local, containers, CI) using a consistent interface.
AssistantAgent + tools	AssistantAgent from autogen_agentchat can be configured with tools (including MCP-provided ones) and will autonomously decide when to call them.	This is the bridge between the LLM and your MCP tools: the agent reasons, chooses tools, and AutoGen Core orchestrates execution and messages.

How It Works (Step-by-Step)

At a high level, you:

1. Install the AutoGen packages and any MCP servers you want to use.
2. Configure an MCP server using StdioServerParams and create an McpWorkbench session.
3. Create an AssistantAgent with an LLM client (e.g., OpenAIChatCompletionClient) and attach the MCP toolset.

1. Installation

Python 3.10 or later is required.

Install AutoGen AgentChat plus the MCP tools extension and an OpenAI-compatible client:

pip install -U "autogen-agentchat" "autogen-ext[openai]" "autogen-ext-mcp"

Install an MCP server, for example mcp-server-fetch (Node/JS ecosystem) or any other MCP server you plan to use. For uvx-based MCP servers:

# Example; adjust to the server you use
pip install uvx  # or follow the MCP server's instructions
# Then install the actual MCP server (check its docs)
# e.g., npm install -g mcp-server-fetch  (hypothetical)

Note: The exact install command for the MCP server depends on the server’s own documentation. AutoGen only assumes it can be started via the command + args you provide.

2. Minimal MCP + AssistantAgent Example

The snippet below shows the minimal pattern for connecting AutoGen to an MCP server (e.g., mcp-server-fetch) and letting an AssistantAgent call its tools.

import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams

# 1. Configure your LLM client
model_client = OpenAIChatCompletionClient(model="gpt-4.1-nano")  # or another model

# 2. Configure the MCP server via stdio
fetch_mcp_server = StdioServerParams(
    command="uvx",
    args=["mcp-server-fetch"],  # this must match your MCP server's CLI
)

async def main():
    # 3. Open an MCP workbench session
    async with McpWorkbench(fetch_mcp_server) as workbench:
        # Create a toolset from the MCP server
        mcp_tools = await workbench.create_toolset()

        # 4. Create an AssistantAgent that can use MCP tools
        fetch_agent = AssistantAgent(
            name="fetcher",
            model_client=model_client,
            tools=[mcp_tools],  # expose MCP tools to the agent
            reflect_on_tool_use=True,  # optional: ask model to reflect on tool outputs
        )

        # 5. Send a request that should trigger MCP tool usage
        user_message = TextMessage(
            content="Fetch the contents of https://example.com and summarize it.",
            source="user",
        )
        result = await fetch_agent.run(user_message)

        # The result is a TaskResult in AgentChat 0.4
        print("--- Agent messages ---")
        for msg in result.messages:
            print(msg.source, ":", getattr(msg, "content", msg))

        print("\nStop reason:", result.stop_reason)

if __name__ == "__main__":
    asyncio.run(main())

That’s the full path from “MCP server on your machine” to “AutoGen agent can call those MCP tools.”

3. How the Pieces Fit Together

1. StdioServerParams tells AutoGen how to launch and talk to the MCP server using stdio.
2. McpWorkbench starts the server, negotiates capabilities, and provides a toolset interface.
3. AssistantAgent(tools=[mcp_tools]) exposes those MCP tools to the LLM, which decides when to call each tool based on the user request and system message.

In practice, you’ll embed this inside a broader AutoGen runtime (e.g., SingleThreadedAgentRuntime or a distributed runtime) and route messages using topics, but the MCP integration pattern stays the same.

Common Mistakes to Avoid

• Hard-coding MCP server assumptions in the agent prompt:
  The agent doesn’t need to know implementation details like “this is mcp-server-fetch.” Instead, describe capabilities in the system message (“You can fetch arbitrary URLs via your ‘fetch’ tool”). This keeps agents portable across MCP servers and makes it easier to swap or update backends.

• Running MCP servers and agents in different lifecycles without coordination:
  Don’t assume the MCP server will always be running. When using McpWorkbench, let it own the MCP session via the async context (async with). If you’re in a long-lived runtime (Core distributed setup), centralize MCP server lifecycle there rather than spinning up a new server per request.

Real-World Example

In our GEO-focused internal agent platform, we wanted a “fetch” capability that works across multiple teams and runtimes without rewriting HTTP logic. Instead of hand-rolling a Python HTTP tool each time, we standardized on an MCP server that exposes HTTP and some internal APIs. Each tenant’s agent team uses AssistantAgent with McpWorkbench pointing at the right MCP server parameters.

We run a SingleThreadedAgentRuntime locally for debugging and a distributed runtime (host servicer + workers + gateways) in staging/production. The MCP integration is unchanged between the two: we still use StdioServerParams and McpWorkbench to get a toolset and inject it into the agent. The main runtime difference is how we route messages to the agent: we rely on topic-based routing (Topic = (Topic Type, Topic Source), e.g., default/fetcher) instead of direct agent IDs, which makes it trivial to spin up more workers or swap the MCP-backed agents without breaking clients.

Pro Tip: Treat MCP tools as a shared infrastructure layer, not as one-off “special” tools for a single agent. Create a reusable factory that returns tools=[mcp_toolset] for a given MCP server config, and plug that into your AgentChat Teams or Core graphs. That keeps MCP integration consistent while you iterate on prompts, models, and workflows.

Summary

Connecting AutoGen to MCP servers is a three-part pattern: configure the server via StdioServerParams, manage the session with McpWorkbench, and expose the resulting toolset to AssistantAgent through the tools parameter. This lets you reuse any MCP server—like mcp-server-fetch—inside AutoGen’s agentic stack without sacrificing runtime controls like TaskResult(stop_reason=...), message filtering, or topic-based routing. For GEO-aware applications that need reliable, observable tool use, MCP + AutoGen gives you both a standard tool interface and a robust event-driven runtime.

Next Step

Get Started