MCP 服务器

MCP（Model Context Protocol）用于将项目连接到外部工具提供方，当前基于 Streamable HTTP 方式接入。
在 ResearchX 中，MCP 服务器为项目级配置，可为会话补充更多可调用工具。

可以配置的内容

• 在项目工作台资产面板中管理 MCP 服务器（MCP 标签）
• 启用或停用某个服务器
• 设置服务器标识名、显示名和 MCP 端点 URL
• 测试连通性并刷新远端工具列表
• 使用白名单 allowed_tools 限制工具可见范围
• 配置鉴权模式（none 或 bearer_token）
• 配置连接稳定性参数（connect_timeout_ms、request_timeout_ms）
• 配置是否向会话暴露工具

入口位置

1. 进入项目工作台
2. 打开资产弹窗（顶部 Agents 按钮）
3. 切到 MCP 页签
4. 点击 New 新建 MCP 服务器

新建服务器

需填写：

• name：服务器短标识（例如 linear）
• display_name：界面显示名称（例如 Linear）
• url：Streamable HTTP 的 MCP 地址（例如 https://example.com/mcp）
• enabled：是否启用该服务器
• expose_tools_to_chat：是否将工具暴露到会话工具列表

鉴权设置

可选：

• none：不附加鉴权
• bearer_token：在请求头中加入 Authorization: Bearer <token>

测试并加载工具

保存后可：

1. 选中目标服务器
2. 点击 Test & Load Tools
3. 查看连接是否成功、工具清单是否可用
4. 按需设置 allowed_tools

工具发现用于：

• 使用前做连通性验证
• 查看工具名称、标题、参数与描述
• 生成或更新 allowed_tools 配置

暴露规则

只有满足以下条件时，MCP 工具才会在会话中可调用：

• 服务器已启用
• expose_tools_to_chat 打开
• 若设置了 allowed_tools，工具在白名单内

安全与确认

MCP 工具会走工具调用链路，必要时可进入确认机制：

• requires_user_confirmation（全局）：所有 MCP 工具都需要确认
• confirmation_tools（按工具）：仅部分工具需要确认

满足确认条件时，审批会进入和其它工具一致的权限面板，与你在会话中的审批流程一致。

命名与可见性

会话侧工具名会被映射为稳定名称：

• mcp_<server_name>_<tool_name>

可避免与项目内已有 action/agent/tool 名称冲突。

运维操作参考

常用操作

• 创建服务器
• 更新配置
• 删除服务器
• 测试连接
• 重新加载发现工具

支持的传输方式

当前只支持 streamable_http。

使用建议

• 建议 name 取固定且简短的值，便于工具名稳定
• 远端服务工具较多时建议先白名单 allowed_tools
• 对较慢接口适当提高超时配置
• 不再使用的服务器建议停用，减少工具噪音

常见问题

测试后看不到工具

常见原因：

• 服务器未开启
• URL 不通或不是 Streamable HTTP MCP 接口
• 超时设置过低，服务端返回前未及时响应
• 服务器本身返回了空工具列表

排查方式：

• 确认 url 与传输方式（当前仅支持 streamable_http）
• 适当提高超时后重试
• 查看服务器日志/网络策略是否有鉴权或拒绝记录

工具发现后在会话里没暴露

请检查以下条件：

• expose_tools_to_chat 已开启
• 服务器状态为 enabled
• 若设置了 allowed_tools，目标工具在白名单内

MCP 调用一直要求确认

在如下场景下属于预期行为：

• requires_user_confirmation 为 true
• 工具名存在于 confirmation_tools 中

在确认安全且可信时，在会话权限面板中批准即可执行。

鉴权报错

对于 bearer_token 模式，请确认 token 未过期且有效。