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.

Quick start#

1
2
3
4
5
6
7

from ag2 import Agent
from ag2.tools import MCPToolkit

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

That is the whole of the common case. MCPToolkit connects to the server, discovers its tools lazily, and exposes each one to the agent as an ordinary function tool. Nothing of yours is handed to the server unless you say so.

Which of the two connection styles you want#

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

• Client-side connection (MCPToolkit) — AG2 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 (MCPServerTool) — 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).

Recipes#

Authenticate to a remote server#

Most real-world MCP servers require authentication. MCPServerConfig is keyword-only, so every setting names itself:

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

from ag2 import Agent
from ag2.tools import MCPServerConfig, MCPToolkit

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

Launch a local server over stdio#

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. MCPStdioServerConfig launches one as a subprocess and pipes the protocol through its stdio:

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

from ag2 import Agent
from ag2.tools import MCPStdioServerConfig, MCPToolkit

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

Connect several servers at once#

MCPToolkit 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 ag2 import Agent
from ag2.tools import MCPStdioServerConfig, MCPToolkit

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

Namespace the tool names#

When two servers expose the same tool name, set tool_name_prefix to keep them apart locally. The prefix is what the model sees; calls sent to the server keep the original name:

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

from ag2 import Agent
from ag2.tools import MCPServerConfig, MCPToolkit

agent = Agent(
    name="Mixed bot",
    tools=[
        MCPToolkit(
            MCPServerConfig(
                server_url="https://github.example.com/mcp",
                tool_name_prefix="github_",
            )
        ),
        MCPToolkit(
            MCPServerConfig(
                server_url="https://docs.example.com/mcp",
                tool_name_prefix="docs_",
            )
        ),
    ],
)

Two remote search tools are then exposed locally as github_search and docs_search. allowed_tools and blocked_tools still match the original remote names.

Like the other config fields, tool_name_prefix accepts a Variable, so the namespace can be resolved from the context at discovery time:

1
2
3
4
5
6
7
8
9

from ag2 import Variable
from ag2.tools import MCPServerConfig, MCPToolkit

toolkit = MCPToolkit(
    MCPServerConfig(
        server_url="https://my-mcp-url.example.com",
        tool_name_prefix=Variable("tenant_prefix"),
    )
)

Declare what a server may ask you for#

A tool call can come back asking for input instead of returning a result. answering= is the one place you declare which of your own resources a server may use, and everything in it is off by default:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import MCPAnswerPolicy, MCPServerConfig, MCPToolkit

agent = Agent(
    name="researcher",
    config=AnthropicConfig(model="claude-haiku-4-5-20251001"),
    hitl_hook=lambda event: input(event.content),  # where a server's question goes
    tools=[
        MCPToolkit(
            MCPServerConfig(
                server_url="https://my-mcp-url.example.com",
                protocol_mode="auto",       # needed for a modern-era server; see below
            ),
            answering=MCPAnswerPolicy(
                elicitation="ask",          # route questions to this agent's human
                sampling=True,              # let the server borrow this agent's model
                roots=["/srv/project"],     # directories to report
                max_rounds=10,              # how often it may come back for more
            ),
        )
    ],
)

MCPToolkit answers what you have enabled and retries the call — the whole loop happens inside the one operation, so nothing is held between calls: the pause is on the remote server and your end is simply waiting.

With no human-input hook configured, a question surfaces the usual "human input was requested but not provided" failure rather than a silent decline: an absent channel is not a refusal, and reporting it as one would hand the server a decline you never made.

Reach a server on the modern protocol era#

Pass protocol_mode="auto". It probes server/discover and falls back to the handshake, which is what a server on revision 2026-07-28 needs — only that era can return a question as the result of a call. The default "legacy" performs the handshake only.

Concepts#

Protocol era#

A protocol era is which family of MCP revisions a connection speaks, and therefore how a request for input travels. protocol_mode chooses how the connection settles on one:

The default stays "legacy" so upgrading AG2 changes no existing connection. Choosing the modern era is a visible line in your code.

Paused run#

A paused run is a turn held mid-flight while someone is asked for something — and on this side of the protocol there never is one. The answer/retry loop runs inside the single operation that opened the session, so nothing is held between your calls: the pause is the remote server's, and your end is simply waiting. Nothing about sticky routing or restarts applies here. The serving guide covers the side that does hold one.

Resolved parameter#

A server may declare a resolved parameter — a tool parameter whose value comes from asking you rather than from the model's arguments. You do not write these; you decide whether to answer them, which is what the answer policy is for. The serving guide covers writing one.

What the MCP answer policy hands over#

elicitation reuses the same two-valued ElicitationPolicy as ACPConfig.elicitation_policy, so the word means one thing across AG2's protocol integrations. sampling is named for the protocol operation rather than "model" on purpose: this side lends your model, while serving's client_model= borrows the caller's — opposite directions that must not share a word.

A capability is advertised only when you enabled it#

So a conforming server never asks for what you would refuse. There is nothing to keep in step by hand: the client derives what it declares from which answering callbacks are supplied, and not enabling one is how it goes unadvertised.

Refusal is asymmetric#

A server that asks anyway is refused, and the two refusals do not look alike:

• Elicitation has a decline action on the wire. A question this agent will not answer is declined, and the server can degrade deliberately.
• Sampling and roots have no such arm. The error returned for one of those ends the client session's request loop, so the tool call fails with that message rather than the server hearing an answer.

A question has to fit a one-line answer#

context.input() is one string in, one string out, so that is the only shape of question this side can answer. A form-mode elicitation with exactly one property is put to your human and answered on that property, carrying the text they typed verbatim — a server that declared the property as a number receives that text, not a number.

Anything else is declined without your human ever seeing it: a URL-mode elicitation, because a text channel cannot confirm that an out-of-band browser flow happened, and a form with more than one property, because splitting one free-text answer across fields would be fabricating data.

What is not forwarded to your model#

The server's max_tokens, temperature, stop_sequences, model_preferences and include_context are all ignored: your configuration governs a call you are paying for, and a third party does not get to pick your model or redirect your spending. Only the messages and the system prompt it sent are used. The completion is one call against the model client, not a turn of your agent — your tools, history and response schema stay out of it, and any tool declarations the request carried are dropped with them, so a borrowed model cannot reach back into the agent that lent it.

Operations#

What a failing answer looks like#

• A server exhausts max_rounds. The tool call fails; the agent sees a tool error it can act on. Raise the bound only if a server legitimately needs that many rounds — an unbounded one could loop the agent.
• A server asks for something you did not enable. Elicitation is declined on the wire; sampling and roots fail the tool call. See Refusal is asymmetric.
• A server asks a question and you configured no human-input hook. The call surfaces the usual "human input was requested but not provided" failure rather than a silent decline.
• A server asks a question this side cannot shape an answer for. A URL-mode elicitation, or a form with more than one property, is declined without your human seeing it. See A question has to fit a one-line answer.
• A server is only reachable on the modern era. "legacy" performs the handshake and nothing else, so a server that announces itself through server/discover is never met there. Set protocol_mode="auto".

Connections are per-operation#

A short-lived MCP session is opened for each operation — discovery, and each tool call — and closed after it. There is no persistent process or pool to manage from your code, and a stdio server's subprocess is launched lazily on the first one.

That is also why the callbacks your answering policy implies are supplied per tool call rather than installed once on the toolkit: your human and your model are reachable only from the live context a call runs in. Discovery is opened without them, so nothing can be asked of you while the server's tools are being listed.

The mcp SDK is a hard dependency of this path#

MCPToolkit imports two private mcp modules at module scope, on the eager ag2.tools import path. A rename in a minor mcp release therefore breaks import ag2.tools for everyone with the mcp extra installed, not only users of protocol_mode="auto". AG2 pins both with a test so an SDK upgrade fails in CI rather than at your import — but pin your mcp version if you deploy from a floating range.

Constructor reference#

MCPToolkit(server, *, middleware=(), answering=None)#

MCPServerConfig (keyword-only)#

MCPStdioServerConfig (keyword-only)#

Every field of both configs except connection_timeout, proxy, verify, encoding and protocol_mode can be a Variable if the value is only known at runtime — handy for injecting per-conversation tokens or workspace paths.

MCPAnswerPolicy#

elicitation ("decline"), sampling (False), roots (()), max_rounds (10) — see What the MCP answer policy hands over.

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 MCPToolkit with MCPStdioServerConfig for those.

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

from ag2 import Agent
from ag2.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. As with MCPToolkit, authorization_token is sent as a bearer Authorization header unless headers already contains Authorization (case-insensitive). Anthropic does not forward headers — only authorization_token is sent.