---

这份手册按症状排查远程 MCP 连接问题。先记住三件事：使用 Streamable HTTP，URL 是 /mcp，请求必须带 Authorization: Bearer <token>。

快速检查

浏览器已登录不代表 MCP 已登录。MCP 不读取浏览器 Cookie。

401 Unauthorized

常见原因：

• 没有带 Authorization。
• Bearer 拼写错误或多了空格。
• 令牌已撤销、过期或复制不完整。
• 令牌属于另一个用户或组织。

处理：

1. 到 API 令牌 重新创建个人令牌。
2. 确认配置中是 Authorization: Bearer <令牌>。
3. 完全重启客户端。
4. 如果仍失败，换一个最小配置只保留 OPC Feed MCP 连接测试。

406 Not Acceptable

客户端请求头没有同时接受 JSON 和 event-stream 时可能出现 406。

如果客户端允许自定义请求头，确保 Accept 包含：

多数现代 MCP 客户端会自动处理；旧客户端更容易遇到这个问题。

连接成功但没有工具

可能原因：

• 当前部署启用了工具分层，默认只暴露 core 工具。
• 用户权限不足，部分治理工具被过滤。
• 管理后台禁用了某些 MCP 工具。
• 客户端缓存了旧工具列表。

处理：

1. 让 Agent 调用 opc_system_tools_search 搜索目标能力。
2. 打开 MCP 工具配置 查看工具是否启用。
3. 重启客户端并刷新工具列表。
4. 需要完整工具列表时，由管理员检查部署环境的 MCP 工具分层设置。

能读但不能写

常见原因：

• 令牌所属用户不是 EDITOR+。
• 当前组织切换不正确。
• 写入目标项目不存在或不可见。
• 工具参数没有通过校验。

处理：

1. 到 组织与成员 检查角色。
2. 先调用 projects_list 或 projects_search。
3. 写事件时明确传 projectSlug。
4. 检查 title、summary、typeSlug 等必填字段。

创建事件失败

常见错误：

推荐让 Agent 先列项目，再创建事件。项目不明确时，应先向人类确认。

Cursor / Claude / 其他客户端差异

不同客户端字段名可能不同：有的叫 streamableHttp，有的叫 http 或 HTTP MCP。关键不是字段名，而是三点：

1. 远程 HTTP MCP。
2. URL 指向 /mcp。
3. Header 带 Bearer。

不要使用旧的本地 stdio 配置连接 OPC Feed；本站没有要求 clone 仓库的本地 MCP 子进程入口。

自托管检查

自托管时额外检查：

• 站点必须能通过 HTTPS 访问。
• 公开地址应正确指向你的域名。
• 反向代理不要丢掉 Authorization 和 Accept 头。
• 生产环境不要把公开 URL 配成 localhost。
• 健康检查优先用应用健康接口或带 Bearer 的 REST 读接口，不要用裸 GET /mcp 当探活。

令牌泄露怎么办

1. 立即到 API 令牌 撤销。
2. 到原客户端或资源中替换新令牌。
3. 检查近期 MCP 调用统计或异常事件。
4. 如果令牌出现在仓库历史中，按密钥泄露流程处理，不要只删当前文件。

下一步

• 远程 MCP 与 API 令牌
• Agent 接入配置
• 资源与密钥