配置自定义 MCP、OAuth 与 Inspector

English | REST API

本指南介绍系统设置中的自定义 MCP 服务器管理。已有内置数据源仍在独立页签中查看，不需要重新添加。

准备

• 先启动产品，并通过服务端打印的 Open to sign in 链接（或本地服务访问令牌）连接浏览器。
• 获取 MCP 提供方的连接说明：本地启动命令，或远程 MCP URL 及认证要求。MCP URL 不是普通网页地址，也不是 LLM 的 OpenAI 兼容基础 URL。
• STDIO 程序运行在 API 后端所在机器，不是在浏览器所在机器，也不会自动进入 Session 沙箱。仅配置可信命令，并在该机器安装所需 Node/Python 等环境；Docker 部署时路径和运行环境必须在容器内可用。

添加与管理服务器

1. 打开“系统设置”，选择“MCP 服务器”，进入“自定义”页签，点击“添加服务器”。
2. 填写名称和可选描述，选择连接方式并按下表填写。
3. 设置“工具超时（秒）”。默认 60 秒，可改为 1-600 秒整数，不能关闭该超时。
4. 表单顶部的“启用此 MCP 服务器”控制整台服务器，新建时默认不勾选。保存后可在列表中启停。
5. 点击服务器名称展开默认收起的详情，再点击“测试连接”。成功后可查看工具数量、说明和输入参数结构；失败时根据错误更正配置并重测。

例如某本地服务通过 node /opt/research-mcp/server.mjs 启动时，“命令”填后端可用的 node 路径，“参数”单独一行填 /opt/research-mcp/server.mjs。这个路径仅为示例，产品不附带该服务。不要把整条 shell 命令填进“命令”。

测试连接可以探测已停用服务器，但不会自动启用它；STDIO 探测会实际启动所配置程序。删除服务器会移除配置、连接器引用及本地授权，不会卸载对应程序。

导入 JSON

点击“导入 JSON”，填写含 mcpServers 对象的配置，例如：

{
  "mcpServers": {
    "Research MCP": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "timeoutSeconds": 60
    }
  }
}

将占位 URL 换成实际端点。导入会校验整个批次，失败时不部分保存；导入后默认停用，需要自行测试和启用。名称重复会报错，最多保存 50 台自定义服务器。不要在公开 issue、截图或共享配置里包含真实凭据。

请求头与环境变量秘密值

HTTP/SSE 选择“无认证 / 请求头”后，可按提供方要求添加 Authorization 等请求头；STDIO 可添加环境变量。字段值在服务端加密保存，重新编辑时显示“已保存的值”，不回填明文。

• 不改键名和值时，保存会保留原秘密。
• 修改已保存的键名后，界面提示重新填写秘密值；未填写时不能保存。原值不会被自动复制到新名称。
• 仅改过键名、未编辑值时，恢复原键名可继续保留原值。
• 主动编辑值并清空，且未更改键名，表示明确保存空字符串，不等于保留旧值。删除整行表示移除该条配置。

直接使用 API 时，null 仅保留同名 key 的旧值。API 的字符串替换和键名删除语义见 REST API。本修复不能找回旧版本已经清空的凭据；这类配置需从原提供方重新取得并填写。

OAuth 登录

OAuth 仅用于 HTTP/SSE，不用于 STDIO。远程 OAuth 地址需 HTTPS，本机回环 HTTP 可用于开发。

1. 在服务器编辑页将“认证方式”设为“OAuth”，移除手动配置的 Authorization 请求头。
2. 按服务商要求填 Client ID、Client Secret、Scope；仅当其支持相应注册流程时，才可留空 Client ID。Client Secret 非空时必须提供 Client ID。
3. 如果服务商使用客户端元数据 URL，填写可访问的 HTTPS 元数据文档地址。产品只接受 URL，不负责托管该文档。
4. 核对页面显示的回调地址。需要预注册的服务商，应把这个完整地址加入其允许列表；localhost、127.0.0.1、域名和端口并不可以随意互换。
5. 保存配置，在服务器详情点击“登录授权”，于新窗口完成登录和同意授权。浏览器拦截弹窗时使用“打开授权页面”。
6. 回到产品查看授权状态，再测试连接和调用工具。需要时可重新授权或取消正在等待的授权。

访问令牌由后端保存和刷新，不必粘贴到本地服务访问令牌输入框，也不应手工复制到请求头。刷新令牌失效、权限不足或连接配置变化时，可能需要重新授权。“清除本地授权”只删除本产品保存的凭据，不撤销服务商端的同意记录；彻底撤销需前往服务商管理页面操作。

第三方的注册策略、Scope、回调白名单与账号权限可能不同，不能仅凭支持 OAuth 就假定零配置兼容。

用 Inspector 验证工具

1. 打开一个 Project 下的 Session，确保 MCP 已启用且测试连接已发现工具。
2. 展开服务器详情，进入“MCP Inspector”。检查其关联的 Session。
3. 选择工具，查看说明和“输入参数结构”，按要求填写“调用参数（JSON）”。
4. 点击“执行工具”，查看成功/失败、耗时，以及“原始返回”和“标准化结果”；可复制结果和展开后的审计记录 ID。
5. 执行中可取消等待，随后可再次调用。取消不能保证撤销远端已经产生的副作用。

Inspector 是真实工具调用，不是模拟预览，也不会调用 LLM 来代填参数。应先了解工具是否会写入或删除数据。它要求存在 Session，以便进入现有调用审计链路；没有 Session 或服务器停用时不能执行。当前 Inspector 聚焦 tools，不是官方独立 Inspector 的完整嵌入版，不提供完整 resources/prompts 浏览器。

让 Agent 使用工具

在目标 Session 的连接器选择中启用对应 MCP。服务器的全局启用和 Session 的有效连接器配置是两道不同的条件；Session 也可能继承 Project/全局配置，请以当前显示的有效选择为准。

Agent 会按任务需要决定是否调用，勾选不代表每次对话必定调用。Inspector 的手动执行不自动修改会话连接器选择，也不等于已授权该 Session 的 Agent 使用所有工具。

常见问题

网络代理配置见配置网络代理。