ag2-mcp

用途

ag2-mcp 解决的是服务端方向的问题：把已有的 AG2 Agent 发布成一个 MCP 服务器，让外部 MCP 客户端（Claude Desktop、Cursor、IDE、MCP Inspector 或任何支持 MCP 的应用）连接后，把你的 Agent 当作一个工具来调用。它也可以在同一服务器上对外暴露可复用的提示模板（prompts）和资源（resources）。

需要注意方向区分：本技能是“服务端”，即让别的 MCP 客户端调用你的 AG2 Agent；如果需要让 AG2 Agent 去调用外部 MCP 服务器的工具，则属于客户端方向，应使用 MCPServerTool / MCP 工具集（另一技能 ag2-use-builtin-tools）。

主要能力

• 通过 ag2.mcp.MCPServer 把 Agent 暴露为单个对话式工具，默认工具名为 ask，接收必填的 message 与可选的 context 字符串。
• 支持两种传输方式：stdio（本地客户端常用）和 streamable HTTP（可交给 uvicorn 运行，MCPServer 本身即 ASGI3 应用并自行管理 lifespan）。
• HTTP 传输可配置 path（默认 /mcp）、stateless、json_response、security 等参数。
• 暴露可复用提示模板：渲染器接收参数字典，返回字符串（单条用户消息）或 PromptMessage 列表，支持同步/异步。
• 暴露静态与模板化资源：read 返回 str 或 bytes，支持同步/异步；资源模板使用 RFC 6570 语法（{var} 匹配单个路径段，{+var} 可跨 /）。
• 多轮会话历史：默认 sessions=True，按会话（HTTP 下以 mcp-session-id 为键）累积对话历史，可通过 SessionConfig 配置 max_sessions（LRU 上限）、ttl（空闲过期秒数）、storage（历史后端，默认内存 MemoryStorage，可换用任意 ag2.history.Storage 如 Redis）。
• 结构化输出：当 Agent 的 response_schema 是对象型 schema（Pydantic 模型、dataclass、dict）时，会作为工具的 outputSchema 声明，并返回经过校验的 structuredContent；标量或联合类型 schema 不声明，按纯文本返回。
• 按请求注入上下文：context_provider 是一个异步钩子，接收已鉴权的 bearer token（未鉴权时为 None），返回 AskContext（variables、tools、prompt），非 None 字段会传入 Agent.ask()。
• 安全（仅 HTTP）：以 OAuth 2.1 bearer 保护端点，服务器仅作为资源服务器，通过 RFC 9728 受保护资源元数据（位于 /.well-known/oauth-protected-resource）声明可信授权服务器并校验令牌；令牌签发仍由外部授权服务器负责。缺失或无效令牌返回 401，权限不足返回 403。
• 进程内测试：ag2.mcp.testing 提供 connect()（低层 ClientSession）与 serve()（基于 ASGI 的 httpx.AsyncClient），无需 socket 或子进程；可配合 ag2.testing.TestConfig 模拟 LLM。

使用方式

1. 安装：pip install "ag2[mcp]"。这是必需步骤，缺少 mcp extra 时 from ag2.mcp import MCPServer 会解析为一个桩，使用时抛出“missing optional dependency”错误。
2. stdio 服务：创建带模型配置的 Agent，构造 MCPServer(agent, name=..., instructions=...)，然后 asyncio.run(server.run_stdio())，并在客户端（如 claude_desktop_config.json）中以 command + args 形式注册。
3. HTTP 服务：app = MCPServer(agent, path="/mcp")，再用 uvicorn.run(app, host=..., port=...) 启动。
4. 自定义工具：可设置 tool_name、tool_description、stream_progress（默认 True，将 Agent 流事件转发为 MCP 进度/日志通知）。
5. 通过 prompts=[Prompt(...)] 暴露提示模板，通过 resources=[Resource(...)] 与 resource_templates=[ResourceTemplate(...)] 暴露资源；只有传入非空列表时才会声明对应能力。
6. 通过 sessions=SessionConfig(...) 调整多轮历史，或 sessions=False 关闭为完全无状态。

适用场景

• 让 Claude Desktop、Cursor 等外部 MCP 客户端直接调用你的 AG2 Agent。
• 对外发布一个 ask 式的对话工具，运行 Agent.ask() 并返回回复。
• 在 MCP 之上提供可复用的提示模板与资源（文件、配置、动态数据）。
• 需要按客户端会话维护多轮历史、OAuth2 保护的 HTTP 端点，或按请求注入上下文。

限制与注意事项

• Agent 必须设置 model config，否则首次工具调用会抛出 MCPAgentConfigError。
• instructions 是面向客户端的握手提示文本，并非 Agent 的 prompt，也不由 Agent prompt 派生，需显式传入。
• stateless=True 的 HTTP 传输不发放 mcp-session-id，因此无论 sessions= 如何设置都保持无状态，若要会话请使用默认 stateless=False。
• security.resource_url 的路径部分必须与 path 一致，否则 MCPServer 初始化抛出 ValueError；oauth2_scheme(url=...) 拒绝非 http(s) URL，且需要自备真实的授权服务器与具体的 TokenVerifier。
• 只有对象型 response_schema 才会声明 outputSchema/structuredContent，标量与联合类型以文本返回。
• 测试中 TestConfig 每次 create() 会构建新的响应迭代器，因此 TestConfig("a", "b") 在两次独立的 call_tools 中不会先返回 "a" 再返回 "b"；会话历史确实会累积，可用自定义测试客户端观察或改用真实模型。
• 关于收费、价格、平台支持范围与效果等信息，资料中暂未提供。