AiPy 怎么接 MCP 服务？客户端配置和开源版 mcp.json 两条路

2026-08-24

AiPy 支持 MCP，但客户端和开源引擎是两套完全不同的接法——一边是图形界面填表单，一边是写 JSON 加敲命令。搜到的教程常常只讲其中一半，你照着做发现界面对不上，就是这个原因。这篇两条路都走一遍。

先明确一件事：官方 FAQ 里对「是否支持 MCP、Skills」的回答是支持，并说明 AiPy Pro 集市中包含官方精品 APP、MCP 工具、Skills，同时支持用户自定义添加。所以「从集市装现成的」和「自己加一个」是两个入口，下面主要讲后者。

一、有些 MCP 是内置的

官方手册写明，AiPy Pro 内置了联网搜索和地理信息服务的 MCP 功能，这两样不用你配。

开源引擎那边也能看到对应的实现。在仓库的 aipyapp/aipy/libmcp.py 里，MCPConfigReader 类把 MCP 分成两套：get_user_mcp() 读你自己的配置文件，get_sys_mcp() 返回内置的系统 MCP。系统 MCP 里注册的正是地图和搜索两个服务，都走 streamable_http 传输。

这里有个前置条件值得注意：get_sys_mcp() 里第一件事就是检查有没有 Trustoken 的 API key，没有的话直接返回空字典，并打一条警告日志说 sys_mcp 不可用。也就是说，内置的这两个 MCP 是和官方账号体系绑定的，没走官方授权就用不上。源码里还有一段配套逻辑：读取用户 MCP 配置时，如果发现某个 server 的 URL 指向官方接口且传输类型是 streamable_http，会自动往它的 headers 里塞上 Authorization: Bearer <key>——这是给官方自家服务做的自动鉴权，你自己加的第三方 MCP 不受影响。

二、Pro 客户端里加一个 MCP

手册以 Tavily 为例演示了完整流程（Tavily 是一款面向 AI 应用的搜索引擎）。步骤是这样的：

第一步，去目标 MCP 服务的网站注册，拿到 API KEY。 这一步和 AiPy 无关，是所有需要鉴权的 MCP 服务的通例。

第二步，在 AiPy Pro 里点添加，配置 MCP 服务。 表单里要填的字段，手册逐条给了说明：

名称：可以自定义填写。它只是给你自己看的标识。
类型、命令、参数：根据 MCP 支持的类型选择，一般 MCP 官方都会有说明。这句话是重点——这几个字段的值不是 AiPy 定的，是你要接的那个 MCP 服务定的，去它的文档里抄。
环境变量：一般填 key。如果 MCP 官方说明里有其他配置，可以继续增加，使用换行分隔。

第三步，点保存，等加载。 保存后会出现一个加载页面，等待 MCP 加载状态变成「已完成」即可关闭窗口。

第四步，验证。 手册给的判断标准很实用：加载完成后，看到 MCP 页面中的工具有具体的数量，则说明 MCP 已经成功配置完成了。 工具数为零就是没接上——这个信号比看有没有报错更可靠。

第五步，用起来。 在 AiPy Pro 下发任务时勾选该 MCP 使用。

最后这一步最容易漏。配好了不等于会被用上，任务里没勾就等于没配。这一点和集市里的智能体是同一个逻辑，详见 AiPy 智能体集市怎么用。

三、开源引擎：配置文件走 mcpServers

开源版没有表单，配置写在一个 JSON 文件里。从 libmcp.py 的 get_user_mcp() 能看到它的读法：打开配置文件、json.load 解析、然后取顶层的 mcpServers 这个键。

config = json.load(f)
servers = config.get("mcpServers", {})

mcpServers 这个键名是关键信息：它和主流 MCP 客户端用的结构是一套。这意味着你在别的工具里已经写好的 MCP 配置块，结构上可以直接搬过来，不用从头学一套新格式。站内的 MCP 通用配置教程讲的就是这个结构，字段含义可以对着看。

手册里也提到了配置文件的位置线索——开源版的配置目录是用户主目录下的 .aipyapp，语言设置 lang="zh" 就写在这个目录的 aipyapp.toml 里。数据迁移那一节则明确给出了这个目录的完整路径：Windows 是 C:\Users\用户名\.aipyapp，macOS 是 /Users/用户名/.aipyapp。

四、开源版的 /mcp 命令族

配好之后怎么管？源码 aipyapp/cli/command/builtin/cmd_mcp.py 里定义了一整套 mcp 子命令，这是开源版排查 MCP 问题的主要工具：

status：显示 MCP 状态。这是不带子命令时的默认行为。
enable / disable：整体启停，配 --user（用户 MCP）或 --sys（系统 MCP）二选一。源码里如果两个都不给，会直接红字提示「请指定 —user 或 —sys」——所以别省这个参数。
server --list：列出用户配置的 MCP 服务器。
server --enable [名字] / server --disable [名字]：单独启停某个 server。源码里这两个参数的 nargs='?' 加了默认值 '*'，意思是不给名字时作用于全部。

status 输出的是一张表，从源码能看到它包含哪几行：系统 MCP 是否启用、用户 MCP 是否启用、服务器总数、已启用服务器数、工具总数、已启用工具数。

这张表的诊断价值很高。总数有、启用数是零，说明配置读到了但没开，去 enable；总数就是零，说明配置文件根本没读进来，去查文件路径和 JSON 格式。两种情况的处理方向完全相反，先看这张表能省很多时间。

五、支持哪几种传输方式

从 aipyapp/aipy/mcp_client.py 的 _create_server_parameters() 能看清楚。它先判断配置里有没有 url 字段：

有 url：再看 transport.type。如果是 streamable_http，走 StreamableHttpParameters；否则走 SSE 那一支。这两种参数类型都是从 MCP 官方 Python SDK 里 import 的（SseServerParameters、StreamableHttpParameters）。
没有 url：走 StdioServerParameters，也就是本地起进程的 stdio 方式。

所以 stdio、SSE、streamable HTTP 三种都支持，判断依据是配置里有没有 url、以及 transport.type 写的是什么。

HTTP 那一支还能配这几个字段，源码里都读了：headers（自定义请求头，鉴权信息一般放这里）、timeout（连接超时）、sse_read_timeout（SSE 读超时）。截至本次抓取，源码给这两个超时设了默认值——timeout 默认 30 秒、sse_read_timeout 默认 120 秒，都可以在配置里覆盖。默认值属于实现细节，会随版本调整，真正要记住的是「这两个键存在、可以覆盖」这件事。

如果你不确定自己要接的那个 MCP 属于哪种类型，站内的 MCP 常见误解和多 server 管理两篇能帮你把概念理顺。

六、惰性连接：为什么 AiPy 不一上来就连所有 MCP

mcp_client.py 里那个类叫 LazyMCPClient，源码注释直接把设计意图写出来了，三条：

仅在调用某个 server 的工具时才连接该 server；
可配置空闲 TTL，超时自动断开；
支持 serverKey:toolName 命名以避免全量扫描。

第三条对使用者最有感知。工具名会被加上服务器前缀，源码里 _qualified() 方法干的就是这件事，返回 f"{server_key}:{tool_name}"。

这解决的是 MCP 用户最熟悉的一个痛点：不同 server 提供了重名工具。 加了前缀之后，tavily:search 和 其他服务:search 天然区分开。站内 MCP 工具命名冲突那篇讲的就是这类问题的通用解法，可以对照着看 AiPy 是怎么选的。

前两条的好处是启动快、不占资源：你配了十个 MCP，不代表启动时要建十个连接。代价是第一次调用某个 server 时会有一次连接开销，慢一点是正常的，别误判成卡死。

源码里还有个细节：它在后台线程维护一个持久事件循环，注释写明是为了「避免每次调用后关闭导致子进程退出」。对 stdio 类型的 MCP 来说这很关键——stdio server 就是个子进程，事件循环一关它就没了。

七、几条报错的出处

对着源码认报错，比猜快得多。

Config file not found: <路径> —— 出自 get_user_mcp() 的 FileNotFoundError 分支。配置文件路径不对或者文件根本没建。注意这个分支是返回空字典而不是抛异常，也就是说 AiPy 会正常启动，只是一个 MCP 都没有。启动没报错不等于配置生效了，还是得看 status 那张表。

Error decoding MCP config file <路径>: <详情> —— JSON 解析失败。手写 JSON 最常见的死法是多一个逗号、少一个引号。这个报错会带上具体位置，照着改就行。

{"error": "Operation timeout", "details": ...} —— 出自 _run_async() 的超时保护，源码里给异步操作设了一个整体超时（当前默认 60 秒）。MCP server 响应太慢或者卡住时会走到这里。

Async execution failed —— 同一个方法里的兜底异常分支，属于「其他没归类的错」，要看 details 才知道原因。

另外源码里有个输出行为值得知道：MCP 工具执行时如果 server 上报进度，会以 [MCP Progress] <server>:<tool>: <百分比> 的格式实时打到终端。看到这类行说明连接是通的、任务正在跑，不是卡了。

如果你的 MCP server 压根起不来，那是 server 侧的问题，站内 MCP server 启动失败排查更对症。

八、两条路怎么选

简单说：用客户端就用表单，别去手搓 JSON；用开源引擎就写 mcp.json 加 /mcp 命令，那边没有图形界面。

客户端的优势是有安全扫描和加载状态反馈，出错时提示更友好；开源版的优势是配置可版本化、可脚本化，适合部署在服务器上批量管理。想把 AiPy 放服务器长期跑的，看 AiPy 怎么安装里的 Linux 部分。

不管走哪条路，接 MCP 等于给 AI 开了一扇通向外部系统的门，权限边界要自己把住。AiPy Pro 的安全中心提供了网络安全规则（可分别针对域名、IP、端口设允许或拒绝），这是配套的护栏。通用的边界思路可以看 MCP 安全边界。

核实边界

本文依据 2026-08-24 抓取的以下官方内容写成：AiPy 官方使用指南 https://www.aipyaipy.com/manual/、官方常见问题页 https://www.aipyaipy.com/faq.html 与 https://www.aipy.app/faq.html，以及开源引擎仓库 https://github.com/knownsec/aipyapp 中 aipyapp/aipy/libmcp.py、aipyapp/aipy/mcp_client.py、aipyapp/cli/command/builtin/cmd_mcp.py 三个文件的源码。

没核到、因此本文没写的部分：mcp.json 在开源版里的确切默认文件名与查找顺序（这部分由调用方传入 config_path，本次抓取的这三个文件里没有写死路径）；客户端表单里「类型」下拉框的具体选项；MCP 配置的完整字段清单（源码只读了本文列出的这几个键，其余未出现的字段无从判断）；各超时默认值在后续版本中是否会调整。作者没有安装运行过 AiPy，本文内容来自官方文档转述与源码阅读，没有实际执行过其中任何命令。