企业官网建设流程全解析

ADK-Python 如何用 to_mcp_server 把整个 Agent 暴露为 MCP 服务器供 Claude Code 等客户端调用

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

如果你的 ADK Agent 需要被 Claude Code、OpenAI Codex、IDE 或其他任何说 MCP（Model Context Protocol）的宿主程序当作一个工具来调用，而又不希望这些宿主导入 ADK 或接触 Agent 内部的各个工具，ADK-Python 提供了to_mcp_server：它把整个 Agent——包括模型循环和它的全部工具——注册为一个以 Agent 命名的 MCP 工具，宿主只需发送一个request字符串，就能拿到 Agent 的最终回复。它是to_a2a的 MCP 对应物。适用前提是：Python 3.10+，并安装了带mcpextra 的 ADK（该功能位于mcpextra 之后）。

准备条件：安装带 mcp extra 的 ADK

ADK 的稳定版通过 pip 安装，要求 Python 3.10+：

pip install google-adk

to_mcp_server标注为@experimental，且依赖 MCP SDK。ADK 的pyproject.toml中定义了名为mcp的可选依赖组（包含mcp>=1.24,<3、anyio>=4.9,<5、aiohttp!=3.14.2），因此需要安装对应的 extra：

pip install "google-adk[mcp]"

注意文档明确说明to_mcp_server是实验性接口，后续版本中行为可能变化；依赖的 MCP SDK 在 1.x 与 2.x 之间服务器类名不同（1.x 为mcp.server.fastmcp.FastMCP，2.x 更名为mcp.server.mcpserver.MCPServer），ADK 已做兼容处理，读者无需自行处理。

把一个 Agent 变成 MCP 服务器

最小示例来自项目文档：定义一个带工具的LlmAgent，调用to_mcp_server得到服务器，然后按传输方式运行。已有的 ADK Agent 可以直接放在dice_agent的位置——to_mcp_server接受BaseAgent。

import random from google.adk.agents import LlmAgent from google.adk.tools.mcp_tool import to_mcp_server def roll_die(sides: int) -> int: """Roll a die with the given number of sides and return the result.""" return random.randint(1, sides) dice_agent = LlmAgent( name="dice_agent", description="Rolls dice with any number of sides and reports the outcome.", instruction="Use the roll_die tool to roll the dice the user asks for.", tools=[roll_die], ) # The whole agent becomes one MCP tool named "dice_agent". server = to_mcp_server(dice_agent) if __name__ == "__main__": server.run(transport="stdio")

运行该文件即在 stdio 上启动 MCP 服务器；MCP 宿主（如 Claude Code）也可以把它作为子进程启动。配置为启动这个文件的宿主会看到一个名为dice_agent的工具，宿主用request字符串调用它，ADK Agent 自己跑完模型和roll_die的循环后返回结果，宿主全程看不到 Agent 的单个内部工具。

配置名称、说明与持久化服务

to_mcp_server的完整签名是to_mcp_server(agent, *, name=None, instructions=None, runner=None)，返回一个FastMCP实例。各选项的作用（以文档的配置表为准）：

两点值得注意：

• 不传runner时的服务全部是内存态：进程重启后不保留。文档明确建议，对于长期运行的网络化服务器，自建Runner（带持久化或可清理的 session 服务）并传入：to_mcp_server(agent, runner=my_runner)。
• 工具描述默认取 Agent 的description：源码中注册工具时description=agent.description or f"Run the {tool_name} agent."，所以给 Agent 写好description会让宿主侧看到更有意义的工具说明。

传输方式：stdio 还是 streamable-http

to_mcp_server只负责生成服务器，传输由调用方决定，server.run(transport=...)的参数即传输名：

• stdio：面向本地宿主，宿主持有进程。stdio 下每个进程只有一条连接，因此该进程内的所有工具调用共享同一个会话。
• streamable-http：面向网络上其他机器的宿主，文档给出的进阶用法就是server.run(transport="streamable-http")——Agent 本身没有任何变化，只换传输。streamable-http 下每个客户端连接各自获得独立会话。

如果只给本机上的一个宿主用，保持文档示例的 stdio 即可；需要跨机访问或让多个客户端各自独立会话时，再切到 streamable-http，并配合上一条的runner注入。

验证：宿主能看到什么、单元如何断言

文档给出的验证方式是看宿主侧的表现：宿主配置启动该文件后，应只看到一个以 Agent 命名的工具，并用request字符串调用它、收到 Agent 的最终响应。中间的非最终文本事件会以 MCP progress notification 形式转发给宿主，宿主可以实时展示 Agent 的工作过程；最终回复中的文本、图片、音频分别映射为TextContent、ImageContent、AudioContent（其他内联数据为EmbeddedResource），多模态输出不会被压平成文本。

仓库的单元测试 test_agent_to_mcp.py 提供了可核对的程序化验证点：

• await server.list_tools()返回恰好一个工具，名字等于 Agent 名（或name参数覆盖后的名字），inputSchema的properties中含request；
• 用客户端会话调用await client.call_tool("assistant", {"request": "hi"})，结果isError为假，result.content[0].text中包含 Agent 的最终文本；
• 同一条连接上的两次call_tool复用同一个 session id（create_session只被调用一次），不同连接各自建立独立 session。

这些断言对应 to_mcp_server 的文档 中"单一工具、每连接一个会话"的描述，实现见 _agent_to_mcp.py。

已知限制

文档列出的限制，直接影响接入方式，需要事先了解：

• 仅文本输入：工具只接受一个request字符串。通过工具调用把媒体传进 Agent 不受支持——MCP 工具参数是宿主模型填写的 JSON，宿主不会往工具参数里放媒体。需要媒体输入时改用 MCP resources 或 elicitation。
• 默认服务是内存态：长期运行的 streamable-http 服务器下会话只增不减、没有淘汰机制，应注入带持久化或清理能力的 session 服务的runner。同一连接上的工具调用预期是串行的，因为它们共享一个会话。
• 实验性：接口位于mcpextra 之后且标注@experimental，后续版本行为可能变化。

继续深入

• 完整文档（含工作原理、会话连续性、进阶用法）：docs/guides/tools/mcp_tool/agent_to_mcp/index.md
• 实现源码：src/google/adk/tools/mcp_tool/_agent_to_mcp.py
• 验证参考（单工具注册、端到端调用、每连接单会话断言）：tests/unittests/tools/mcp_tool/test_agent_to_mcp.py
• 相关示例目录：contributing/samples/mcp

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python