ag2-mcp

Serving an AG2 agent as an MCP server

ag2.mcp.MCPServer turns an AG2 Agent into a Model Context Protocol server: MCP clients (Claude Desktop, Cursor, the MCP Inspector, or any MCP-speaking app) connect and call your agent as a tool. It can also expose prompts and resources alongside the agent.

Server side vs. client side — read this first

There are two opposite directions, and this skill is only one of them.

Direction	You want…	Use
Server (this skill)	other MCP clients to call your AG2 agent	ag2.mcp.MCPServer
Client	your AG2 agent to call an external MCP server's tools	MCPServerTool / MCP toolkits — see ag2-use-builtin-tools

If the user says "let Claude Desktop talk to my agent", "publish my agent over MCP", or "host an MCP endpoint" → this skill. If they say "give my agent the GitHub MCP tools" or "connect to an MCP server" → ag2-use-builtin-tools.

When to use

• Expose an AG2 agent so external MCP clients (Claude Desktop, Cursor, IDEs) can call it.
• Publish a single conversational ask-style tool that runs Agent.ask() and returns the reply.
• Serve reusable prompts (templates) and resources (files/config/dynamic data) over MCP.
• Need multi-turn history per client session, OAuth2-protected HTTP, or per-request context injection.

Installation

pip install "ag2[mcp]"

Required. Run this install before delivering the code. Without the mcp extra, from ag2.mcp import MCPServer resolves to a stub that raises a "missing optional dependency" error on use.

60-second recipe — serve an agent over stdio

This is the form local MCP clients (Claude Desktop, Cursor, MCP Inspector) expect. The server reads/writes MCP frames over stdin/stdout.

import asyncio

from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.mcp import MCPServer

agent = Agent(
    name="assistant",
    prompt="You are a helpful assistant.",
    config=OpenAIConfig(model="gpt-4o-mini"),
)

# The agent is exposed as ONE conversational tool, named "ask" by default,
# taking a required `message` and an optional `context` string.
server = MCPServer(
    agent,
    name="assistant-mcp",                 # serverInfo.name in the handshake
    instructions="Ask me anything.",       # client-facing usage hint (NOT the agent prompt)
)

if __name__ == "__main__":
    asyncio.run(server.run_stdio())