# 连接远程 MCP 服务

填写远程地址与认证，启用工具并验证资源权限。

## 先确定是否需要远程 MCP

远程 MCP 让 Agent 通过服务端点使用外部工具。适合已有 MCP 地址的知识库、业务系统或内部工具。Nexus 当前自定义表单提供 HTTP、SSE 和本地 STDIO 三种类型；本页介绍前两种。

如果能力页已有对应连接器，先检查该连接器的配置方式。自定义 MCP 的认证选项是无认证、Bearer Token 和自定义请求头，不提供通用 OAuth 登录向导。需要浏览器授权的服务，应使用产品已有的连接器入口或服务方明确支持的其他接入方式。

## 准备连接信息

向服务提供方确认传输类型、完整端点、认证方式和一个适合测试的只读工具。服务首页能打开，不说明该地址就是 MCP 端点。

| 情况 | 选择 |
| --- | --- |
| 文档明确写 HTTP 或 Streamable HTTP | HTTP，填写对应端点 |
| 文档明确写 SSE | SSE，填写对应端点 |
| 文档只给启动程序和参数 | 使用[本地 MCP](/docs/mcp-local) |
| 文档只说明网页版登录 | 先确认是否提供 MCP 接口 |

HTTP 和 SSE 是传输选择，不能靠随意把 URL 的 `/mcp` 改为 `/sse` 来切换。使用服务方给出的完整地址。

## 添加服务

打开 **能力 → 连接器 → 自定义 MCP → 添加 MCP**。在弹窗中填写名称，选择 HTTP 或 SSE。

![真实 Nexus App 的 HTTP MCP 表单与 Bearer Token 认证字段](/images/docs/mcp-http-form.png)

| 字段 | 填写规则 | 示例 |
| --- | --- | --- |
| 名称 | 1 至 64 字符，首字符必须是字母或数字，其余可用字母、数字、点、下划线和连字符 | `team-docs` |
| 服务地址 | 有效 HTTP 或 HTTPS 地址 | `https://mcp.example.com/mcp` |
| 认证 | 与服务实际要求一致 | Bearer Token |

示例域名不提供服务，需替换成自己的端点。名称不能以点、下划线或连字符开头。把中文用途写进自己维护的说明，不要用中文作为这个配置名称。

## 三种认证怎样填写

### 无认证

只用于服务明确不要求认证的情况。选择无认证不会取消服务器的认证要求。受保护端点返回 401 时，应回到认证配置检查，而不是扩大 Agent 权限。

### Bearer Token

在令牌字段填写令牌本身。Nexus 负责构造认证请求头，不要重复加上 `Bearer ` 前缀，也不要把令牌拼到 URL 中。

### 自定义请求头

每行填写一个请求头名称和值。例如服务要求 `X-API-Key` 时，名称填 `X-API-Key`，值填服务提供的 Key。若服务要求多个头，分别添加，不能把整段 JSON 粘进单个名称字段。

新增的每行必须有名称和值，同名键不能重复。误加的空行应删除。请求头名称和值都由服务文档决定，不要同时尝试多个猜测的认证头。

## 保存后查看工具目录

保存后打开服务详情。远程服务的详情页会读取服务器信息和工具目录，可以查看工具说明、参数及必填标记。先找准备测试的工具，再决定 Agent 能访问哪些资源。

“已启用”说明服务允许在聊天中使用，不等于本次远程发现已经成功。目录读取失败时使用重试入口，并检查网络和认证。目录为空也可能是服务没有公布工具，不能把它当成已经可以执行所有业务操作。

## 为当前任务启用并验证

到目标 Agent 的工具页选择默认连接器，或在当前会话添加菜单中启用对应服务。随后发出一项范围明确的请求。

```text
使用 team-docs 的只读工具查找标题含“入门”的文档，最多返回三条。
列出标题与来源，不修改文档。如果没有可用工具或资源权限，说明停在哪一步。
```

这个请求是教学示例，检索方式以你的服务实际工具为准。检查结果是否来自预期账号、空间和文档。工具成功返回空列表时，可以改用一份已知可访问文档验证，区分“没有匹配项”和“没有权限”。

## 轮换和保留秘密字段

已保存的令牌和请求头值不回显，编辑时显示“已保存；留空则保持不变”。保留该行并留空表示沿用旧值，输入新值表示替换。删除请求头行表示移除该项，不能把删行当成保留旧值。

切换认证类型前确认新方式可用。更换令牌后做一次只读验证，再恢复依赖它的定时任务。历史配置提示待恢复时，需要原加密密钥或重新录入完整凭据，反复点击重试不会重建丢失的密钥。

## 按失败位置排查

| 现象 | 检查 | 恢复后的验证 |
| --- | --- | --- |
| 表单拒绝名称 | 首字符、长度、允许字符 | 保存后重新打开 |
| 无法连接或超时 | Nexus 运行机器的 DNS、代理和端点 | 重新读取工具目录 |
| 401 或 403 | 令牌是否过期、认证头及账号权限 | 调用一个已知有权限的只读工具 |
| 返回网页或 404 | URL 是否是 MCP 端点、传输是否匹配 | 工具目录出现预期工具 |
| 目录可读，聊天找不到工具 | 服务开关、Agent 和当前会话启用范围 | 在目标会话重新调用 |
| 工具能运行，某份文档拒绝访问 | 外部账号对该资源的权限 | 用同账号读取该文档 |

Web 版检查服务器出站网络；服务器里的 `localhost` 指服务器或容器自身。需要停用时关闭服务开关，再检查仍引用该能力的任务。已发生的外部写入不会因停用而撤回。