MCP 工具接入

Agently 支持把 MCP Server 暴露的工具批量接入 Agent，并由模型按需调用。

适合什么时候读

• 你已经理解 Tools 的基本概念
• 你手里已有 MCP Server，希望直接接进 Agently
• 你希望尽量少写自定义工具包装

你会学到什么

• HTTP 和本地脚本两种 MCP 接入方式
• MCP 工具和普通 Agently 工具之间的关系
• 工具不调用或调用失败时的排查方向

1. 版本要求

v4.0.8.1 起，MCP 依赖要求为：

• fastmcp >= 3

若你本地使用旧版本 fastmcp，建议先升级。

2. 基础接入（HTTP MCP）

import asyncio
from agently import Agently

agent = Agently.create_agent()

async def main():
    await agent.use_mcp("http://localhost:8080/mcp")
    result = await agent.input("请用工具计算 333 + 546").async_start()
    print(result)

asyncio.run(main())

use_mcp(...) 会完成：

1. 拉取 MCP 工具列表
2. 转换为 Agently 工具 schema
3. 注册到当前 Agent 的工具集合

3. 本地脚本方式（stdio）

import asyncio
from pathlib import Path
from agently import Agently

agent = Agently.create_agent()

async def main():
    mcp_script = Path("./cal_mcp_server.py").resolve()
    await agent.use_mcp(str(mcp_script))
    result = await agent.input("请用工具计算 21 * 34").async_start()
    print(result)

asyncio.run(main())

4. 与工具体系的关系

MCP 工具接入后，本质上与 register_tool 注册出的工具一致：

• 会参与 use_tools 自动工具判断
• 调用日志会写入 extra.tool_logs
• 可配合 runtime.show_tool_logs 做观测

5. 常见问题

5.1 报错：无法导入 fastmcp

• 检查 Python 环境是否安装 fastmcp>=3
• 确认运行时与安装环境一致（venv/poetry）

5.2 MCP 工具已接入但模型不调用

建议：

• 优化工具描述与参数说明（让模型更容易判断）
• 提示词里显式要求“必要时调用工具”
• 先用简单问题验证链路，再逐步复杂化

5.3 工具调用失败但主流程继续

MCP 调用失败时，工具返回可能包含错误结构（例如 {"error": ...}）。 建议在最终输出阶段做异常分支处理，避免把失败结果当成功数据使用。

下一步去哪

• 还没看过 Tools 总览：回到 工具系统总览
• 想把 MCP 放进更完整流程：看 工作流与扩展总览

Related Skills（可选）

• agently-agent-extensions