MCP Servers#

MCP (Model Context Protocol) is a protocol introduced by Anthropic that aims to standardize how tools and prompts are exposed to LLMs. It can be thought of as a superset of regular Tools, created to solve two problems:

1. Each LLM provider had its own tool schema and types, making tools non-portable across providers.
2. There was no standard way to give an LLM a scoped, context-optimized surface to invoke APIs, RPCs, and similar remote capabilities.

Two ways to connect an MCP server#

Autogen supports both ways MCP servers are typically wired into an agent:

• Client-side connection — Autogen connects to the MCP server itself, discovers the tools, and executes them locally. The LLM only ever sees ordinary function tools. Works with every provider. Supports both remote servers (HTTP / streamable-http) and local servers (subprocess speaking MCP over stdin/stdout).
• Provider-side connection — the MCP server URL and credentials are forwarded to the LLM provider, which connects to the server and invokes the tools on its end. Only works with providers that natively support it (e.g. Anthropic).

Client-side: MCPServer#

MCPServer is a Toolkit — it discovers the server's tools lazily and exposes each one as a regular function tool to the agent. It accepts either a remote URL/MCPServerConfig or an MCPStdioServerConfig for a locally-launched subprocess; the rest of the agent doesn't care which transport is in use.

Remote servers (HTTP)#

The simplest form takes a URL string and uses the streamable-http transport:

1
2
3
4
5
6
7

from autogen.beta import Agent
from autogen.beta.tools import MCPServer

agent_with_mcp = Agent(
    name="Weather bot",
    tools=[MCPServer("https://my-mcp-url.example.com")],
)

Most real-world MCP servers require authentication. Use MCPServerConfig for typed configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from autogen.beta import Agent
from autogen.beta.tools import MCPServer, MCPServerConfig

agent_with_mcp = Agent(
    name="Weather bot",
    tools=[
        MCPServer(
            MCPServerConfig(
                server_url="https://my-mcp-url.example.com",
                authorization_token="XXXXXX",
            )
        )
    ],
)

MCPServerConfig also accepts headers, allowed_tools, blocked_tools, description, and a server_label for logging, plus transport-level knobs connection_timeout (default 30.0), proxy, and verify (TLS verification, default True). The first group — server_url, server_label, authorization_token, description, allowed_tools, blocked_tools, headers — can also be a Variable if the value is only known at runtime; connection_timeout, proxy, and verify take plain values only.

Local servers (stdin/stdout)#

Many MCP servers ship as CLIs that speak MCP over their own stdin/stdout — npx -y @modelcontextprotocol/server-filesystem, uvx some-mcp-server, a Python script in your repo, etc. Use MCPStdioServerConfig to launch one as a subprocess; Autogen pipes the MCP protocol through its stdio.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from autogen.beta import Agent
from autogen.beta.tools import MCPServer, MCPStdioServerConfig

agent_with_local_mcp = Agent(
    name="Filesystem bot",
    tools=[
        MCPServer(
            MCPStdioServerConfig(
                command="npx",
                args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"],
            )
        )
    ],
)

You can pass environment variables, a working directory, and the usual filtering options:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from autogen.beta import Agent
from autogen.beta.tools import MCPServer, MCPStdioServerConfig

agent_with_local_mcp = Agent(
    name="GitHub bot",
    tools=[
        MCPServer(
            MCPStdioServerConfig(
                command="uvx",
                args=["mcp-server-github"],
                env={"GITHUB_TOKEN": "ghp_XXXXXX"},
                cwd="/srv/workspace",
                allowed_tools=["list_issues", "create_issue"],
                server_label="github",
            )
        )
    ],
)

MCPStdioServerConfig accepts command, args, env, cwd, server_label, description, allowed_tools, blocked_tools, and encoding (default "utf-8"). All of these except encoding can be a Variable if the value is only known at runtime — handy for injecting per-conversation tokens or workspace paths.

Multiple servers#

MCPServer is just a toolkit, so you can register as many as you need — and freely mix remote and local ones:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from autogen.beta import Agent
from autogen.beta.tools import MCPServer, MCPStdioServerConfig

agent_with_mcp = Agent(
    name="Mixed bot",
    tools=[
        MCPServer("https://my-mcp-url.example.com"),
        MCPServer("https://my-mcp-url2.example.com"),
        MCPServer(
            MCPStdioServerConfig(
                command="npx",
                args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
            )
        ),
    ],
)

Provider-side: MCPServerTool#

MCPServerTool does not open a connection — it ships the server URL and credentials to the LLM provider as part of the request. The provider is then responsible for connecting to the MCP server and dispatching tool calls. Because the provider only accepts a URL, this path does not support local stdio servers — use MCPServer with MCPStdioServerConfig for those.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from autogen.beta import Agent
from autogen.beta.tools import MCPServerTool

agent_with_mcp = Agent(
    name="Weather bot",
    tools=[
        MCPServerTool(
            server_url="https://my-mcp-url.example.com",
            server_label="weather",
            authorization_token="XXXXXX",
        ),
    ],
)

MCPServerTool also accepts description, allowed_tools, blocked_tools, and headers. All constructor parameters can be a Variable if the value is only known at runtime.