AQBot MCP 配置实战：连接 stdio、SSE 与 StreamableHTTP 工具服务器的完整指南

AQBot 是一款跨平台 AI 对话 + AI Agent + AI 网关桌面客户端，内置 MCP（Model Context Protocol）客户端，支持通过stdio、SSE、StreamableHTTP三种传输方式连接工具服务器，让 AI 在对话中直接调用网页抓取、文件读写、数据库查询等外部工具。本文将带你从零开始完成 MCP 配置，并附常用示例与排错技巧。

什么是 MCP 服务器

MCP 是一种开放协议，让 AI 模型与外部工具和数据源交互。通过 MCP，模型可以在对话中调用网页抓取、文件系统、数据库查询等工具，大幅扩展 AI 的实际能力。

AQBot 在客户端内置了完整的 MCP 支持（类型定义见 src/types/mcp.ts）：

• 三种传输协议— stdio、SSE、StreamableHTTP 全覆盖
• 内置工具服务器— 开箱即用的网页抓取与文件搜索，无需安装
• 权限策略— 每次询问 / 允许安全操作 / 允许全部，灵活控制风险
• 超时控制— 可分别配置"发现超时"与"执行超时"，避免卡死

三种传输协议怎么选

💡 简单判断：工具装在你电脑上 → 用stdio；工具部署在远端服务器 → 用SSE或StreamableHTTP。

快速入门：进入 MCP 服务器设置

操作路径：设置 → MCP 服务器。

左侧是服务器列表，分为"内置工具"和"自定义"两组，右侧是当前服务器的详细配置面板（界面实现见 src/components/settings/McpServerSettings.tsx）。列表项旁的传输标签一目了然：

• 🟦STDIO（蓝色，终端图标）— 本地子进程
• 🟧SSE（橙色，广播图标）— 远程 SSE
• 🟩HTTP（绿色，地球图标）— StreamableHTTP

每个服务器右侧有一个开关，可随时启用或停用，不需要删除配置。

第一步：配置 stdio 本地服务器

大多数 MCP 服务器以 stdio 模式运行：AQBot 在本地启动一个进程，通过标准输入/输出与它通信。

表单创建步骤

1. 在 MCP 服务器页面点击添加 MCP 服务器
2. 在弹窗中选择"表单创建"标签页
3. 填写名称（取个易识别的名字）
4. 传输协议选择Stdio
5. 填写启动命令与参数：
   • 命令：如npx、uvx、python
   • 参数：空格分隔，如-y @modelcontextprotocol/server-name
6. （可选）在环境变量区按KEY=VALUE每行一条填写，例如API_KEY=xxx
7. 保存后 AQBot 自动连接并拉取可用工具列表

典型配置示例

网页抓取工具（用uvx启动）：

命令: uvx 参数: mcp-server-fetch

文件系统服务器（用npx启动，指定可访问目录）：

命令: npx 参数: -y @modelcontextprotocol/server-filesystem /Users/你的用户名/Documents

⚠️安全提示：文件系统服务器会授予 AI 对指定目录的读写权限，请只暴露必要的目录，避免暴露根目录或敏感目录。

第二步：连接 SSE 远程服务器

如果 MCP 服务器部署在远程（比如公司内网托管），选择SSE传输：

1. 传输协议选择SSE
2. 端点地址填写服务器 URL，如https://mcp.example.com/sse
3. 自定义请求头（可选）：按Authorization=Bearer xxx每行一条，用于鉴权
4. 保存即可

第三步：连接 StreamableHTTP 服务器

StreamableHTTP 是更新的远程协议，支持双向流式传输，配置方式与 SSE 类似：

1. 传输协议选择StreamableHTTP
2. 端点地址填写 URL，如https://mcp.example.com/mcp
3. 如需鉴权，在自定义请求头中添加Authorization=Bearer <你的令牌>
4. 保存后测试连接

📌 在内部存储中，StreamableHTTP 与 http 类型统一归为http传输（见 src/types/mcp.ts 中的McpTransport定义）。

进阶：JSON 一键导入批量配置

如果已有现成的 MCP 配置（例如从其他工具导出的mcpServers格式），可以直接粘贴 JSON 导入，支持批量添加。弹窗中的"导入创建"标签页接受标准格式：

{ "mcpServers": { "my-tool": { "command": "npx", "args": ["-y", "@some/mcp-server"], "env": { "API_KEY": "your-key" } }, "remote-server": { "type": "sse", "url": "https://mcp.example.com/sse" }, "http-server": { "type": "streamablehttp", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer xxx" } } } }

AQBot 会自动识别command（判定为 stdio）、type（sse/streamablehttp/http）与url/endpoint字段，一次粘贴、多个服务器全部导入成功（识别逻辑见 McpServerSettings.tsx）。

掌握权限策略与超时参数

权限策略

每个服务器可独立设置permissionPolicy，决定工具调用时是否需要人工确认：

超时设置

• 发现超时（discoverTimeoutSecs）：5~300 秒，用于连接服务器并获取工具列表
• 执行超时（executeTimeoutSecs）：5~600 秒，限制单次工具调用的最长耗时

网络较慢的远程服务器建议适当调大发现超时；执行耗时较长的工具（如批量爬取）调大执行超时即可。

工具循环上限

在设置 → 对话中可以限制单次回复中模型连续调用 MCP 工具的轮数。数值较低可减少耗时和成本，数值较高适合更长的自动化工具流程。

开箱即用：AQBot 内置工具

AQBot 自带两个无需安装的 MCP 工具服务器，在服务器列表的"内置工具"分组中默认显示，打开开关即可使用：

@aqbot/fetch — 网页抓取

@aqbot/search-file — 文件操作

在对话中使用 MCP 工具

普通对话与 Agent 模式的区别

• 普通对话：勾选 MCP 服务器后，工具会提供给模型；默认权限策略下每次调用前会请求确认。普通 Chat 的 MCP 链路不会执行终端命令。
• Agent 模式：在输入框底部切换到 Agent，MCP 工具会与内置 Agent 工具（读写文件、执行命令）一起提供给模型，工作目录是进程起始 CWD，而非文件系统沙箱。

工具执行面板

当模型调用 MCP 工具时，消息中会出现工具执行面板，展示：

• 工具名称— 被调用的工具和所属服务器
• 输入参数— 模型传给工具的参数
• 执行状态— 等待确认、执行中、已完成或失败
• 返回结果— 工具执行后返回的数据

点击面板可展开查看完整输入输出，方便调试 AI 的工具使用行为。

常见问题排查

Q1：连接测试失败怎么办？

1. 先在设置页运行连接测试，查看具体报错
2. stdio 服务器：确认命令在本机终端能直接运行（npx/uvx是否已安装）
3. SSE/StreamableHTTP：确认 URL 可达、请求头鉴权正确
4. 首次拉取工具较慢时，适当调大"发现超时"

Q2：工具列表是空的？

确认服务器开关已打开，然后点击刷新工具重新发现工具。部分服务器需要重启后才会暴露完整工具集。

Q3：如何停用某个工具？

不需要删除服务器，直接把开关关闭即可，配置保留随时可再启用。

Q4：远程服务器需要鉴权？

在"自定义请求头"中按KEY=VALUE格式每行一条添加，最常见的就是Authorization=Bearer <令牌>。

总结

通过本文的步骤，你可以在 AQBot 中快速接好 stdio、SSE 与 StreamableHTTP 三类工具服务器，配合权限策略与超时参数，安全地把 AI 的能力延伸到文件、网页与数据库等外部世界。更多细节可参考官方文档 website/docs/zh/guide/mcp.md，数据流实现见 src/stores/mcpStore.ts。