如何用 LlamaIndex BasicMCPClient 把现有 MCP 服务器的工具接入 FunctionAgent

如何用 LlamaIndex BasicMCPClient 把现有 MCP 服务器的工具接入 FunctionAgent

【免费下载链接】llama_index LlamaIndex is the leading document agent and OCR platform 项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

如果你手里已经有一个运行中的 MCP（Model Context Protocol）服务器，想让它暴露的工具（tools）被 LlamaIndex 的 FunctionAgent 调用，而不必把工具逻辑重写成 LlamaIndex 原生 ToolSpec，LlamaIndex 提供了 llama-index-tools-mcp 包来承担这个集成。整个路径是：用 BasicMCPClient 连上现有 MCP 服务器 → 用 McpToolSpec 把服务器上的工具转换成 FunctionTool 列表 → 把列表传给 FunctionAgent。本文基于仓库中的 MCP 工具接入文档、llama-index-tools-mcp 包的 README 和 集成包示例 notebook 写成。

准备条件

• 已有一个可访问的 MCP 服务器。它可能是远程的（SSE 端点或 Streamable HTTP 端点），也可以是本地进程（stdio），例如仓库测试目录里自带的 server.py 就是一个通过 stdio 运行的示例服务器。
• Python 环境满足 llama-index-tools-mcp 的 pyproject.toml 要求：requires-python = ">=3.10,<4.0"，依赖 mcp>=2.0.0,<3 和 llama-index-core>=0.13.0,<0.15。
• Agent 需要一个 LLM。文档和示例统一以 llama-index-llms-openai 的 OpenAI 为例（文档中出现的模型名有 gpt-5-mini 和 gpt-4o 两种，按需替换）。

安装集成包：

pip install llama-index-tools-mcp

用 BasicMCPClient 连接现有 MCP 服务器

BasicMCPClient 支持三种传输方式，第一个参数 command_or_url 决定连接目标（见 client.py）：

from llama_index.tools.mcp import BasicMCPClient

# Server-Sent Events：端点路径以 /sse 结尾时走 SSE 传输
sse_client = BasicMCPClient("https://example.com/sse")

# Streamable HTTP：默认的 HTTP 传输方式
http_client = BasicMCPClient("https://example.com/mcp")

# 本地进程：以 stdio 方式启动并连接一个本地 MCP 服务器
local_client = BasicMCPClient("python", args=["server.py"])

把 https://example.com/sse、https://example.com/mcp 和 server.py 替换成你自己的服务器地址或脚本路径。连接本地进程时，args 传给 StdioServerParameters，还可以用 env 参数给子进程设置环境变量。

客户端常用参数（来自 client.py 的 docstring）：

• timeout：HTTP 操作超时，默认 30 秒；
• sse_read_timeout：SSE 读超时，默认 300 秒；
• headers：传给 SSE 客户端或 streamable HTTP 客户端的请求头，需要鉴权头时使用；
• http_client：自定义 httpx 异步客户端，仅在 Streamable HTTP 传输下可用（例如绕过自签名证书问题）。

如果服务器启用了 OAuth 2.0 保护，用 BasicMCPClient.with_oauth 创建带认证的客户端，并传入 client_name、redirect_uris、redirect_handler、callback_handler；不传 token_storage 时默认使用内存存储，代码会给出警告：token 在重启后丢失。生产环境按 README 的示例实现自定义 TokenStorage。

把 MCP 工具转换为 LlamaIndex FunctionTool 列表

连接成功后，用 McpToolSpec 完成转换，这是文档给出的最常见用法：

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

# 连接到你的 MCP 服务器（示例地址，替换为实际端点）
mcp_client = BasicMCPClient("http://127.0.0.1:8000/sse")
mcp_tool_spec = McpToolSpec(client=mcp_client)

# 异步环境（推荐）
tools = await mcp_tool_spec.to_tool_list_async()

McpToolSpec 构造参数（见 base.py）：

• allowed_tools：按工具名过滤，例如 allowed_tools=["echo"]；列表为空时返回空工具列表并记录警告；
• include_resources=True：把服务器的 resources 也一并转成工具加入列表；
• global_partial_params / partial_params_by_tool：为工具预置部分参数，预置的字段会同时从工具的 schema 中移除，agent 不再需要传这些参数。

一个同步/异步的使用限制需要注意：to_tool_list() 是同步接口，在已有事件循环运行的异步环境中调用会抛出 RuntimeError，此时应改用 to_tool_list_async()。

如果不想要 McpToolSpec 这一层，也可以直接用工具函数拿 FunctionTool 列表：

from llama_index.tools.mcp import get_tools_from_mcp_url, aget_tools_from_mcp_url

# 异步
tools = await aget_tools_from_mcp_url("http://127.0.0.1:8000/sse")

接入 FunctionAgent

拿到 FunctionTool 列表后，直接传给 FunctionAgent：

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

agent = FunctionAgent(
name="Agent",
description="Some description",
llm=OpenAI(model="gpt-5-mini"),
tools=tools,
system_prompt="You are a helpful assistant.",
)

response = await agent.run("Your query here")

这里的 llm 和 system_prompt 按你的场景替换。示例 notebook 展示了一个完整的交互式用法：通过 agent.run(…) 返回的 handler 遍历 stream_events()，在 verbose=True 时打印 ToolCall（工具名与入参）和 ToolCallResult（工具输出）事件，可以直观看到 agent 是否真的调用了 MCP 服务器上的工具。

验证接入是否成功

仓库测试目录 test_tools_mcp.py 给出了可复用的判断方式，它用 stdio 方式连上自带的测试服务器 server.py（BasicMCPClient("python", args=[SERVER_SCRIPT], timeout=5)），然后断言：

• McpToolSpec(client).to_tool_list() 返回的工具数大于 0，说明连接和工具拉取成功；
• McpToolSpec(client, include_resources=True) 的工具数大于不含 resources 时的数量，说明 resources 被正确附加；
• McpToolSpec(client, allowed_tools=["echo"]) 只返回 1 个工具且 tools[0].metadata.name == "echo"，说明按名过滤生效。

你也可以按示例 notebook 的做法直接打印核对：

tools = await mcp_tool_spec.to_tool_list_async()
for tool in tools:
print(tool.metadata.name, tool.metadata.description)

输出的名称和描述应与你 MCP 服务器上注册的工具一致。绕过 agent 单独验证服务器连通性时，可以直接调用客户端方法（见 README）：

# 列出服务器上所有工具
tools = await client.list_tools()

# 直接调用某个工具
result = await client.call_tool("calculate", {"x": 5, "y": 10})

端到端验证则跑一次 agent.run(…)，确认响应基于工具结果生成（如 notebook 中 agent 调用 fetch_ipinfo 工具获取 IP 信息的交互）。

限制与已知约束

• 端点类型要与传输匹配：URL 路径以 /sse 结尾（或查询参数 transport=sse）时 BasicMCPClient 走 SSE 传输，否则默认走 Streamable HTTP。你的服务器暴露的是哪种端点，客户端就要按对应地址连接，文档示例中 http://127.0.0.1:8000/sse 即对应示例服务器以 –server_type=sse 启动时的默认端口。
• 异步环境禁用同步接口：to_tool_list() 在事件循环运行时抛异常，只能用 to_tool_list_async()。
• OAuth 默认 token 存储是内存态：不传 token_storage 会收到 UserWarning，进程重启后 token 丢失。
• stdio 连接是本地进程：BasicMCPClient("python", args=["server.py"]) 会在你的环境里启动子进程，确保对应脚本依赖（如示例中 mcp 包）已安装。
• 完整功能演示可参考 mcp.ipynb：它启动 mcp_server.py（python mcp_server.py –server_type=sse，需配置 IPINFO_API_TOKEN 和 OpenAI key 的环境变量）后用 agent 查询 IP 信息，属于带外部依赖的可选分支，不是接入流程的必要条件。

下一步

• Agent 的更多用法（事件流、子 agent 等）见框架文档中的 Agents Guide（llamaindex_mcp.md 中引用）。
• 反向场景——把自己的 LlamaIndex workflow 或工具发布为 MCP 服务器——可用 workflow_as_mcp，见 convert_existing.md。

【免费下载链接】llama_index LlamaIndex is the leading document agent and OCR platform 项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考