Claude Code 是 Anthropic 的 AI 编程智能体，通过 CLI 配置和管理 MCP 服务；接入 ONES MCP 后，它以授权身份读取和操作 ONES 中的工作项、知识库、工时等数据。本文按“端点地址→传输方式→认证方式→首次只读调用→验收记录”的顺序，给出可逐项核对的检查点。适用范围为国内版公有云产品手册所描述的能力；国内详细配置页没有独立的 Claude Code 教程，具体连接命令、OAuth 回调与工具权限的端到端表现仍需在目标环境按端点协议验证，私有部署按文内条件确认。
要点总览（TL;DR）
- 核对顺序按“端点地址→传输方式→认证方式→首次只读调用→验收记录”推进，每一步只确认一件事，便于定位失败层级。
- 团队 MCP 服务器地址从 ONES 个人中心的已授权 MCP 客户端页面复制，路径为 /mcp；OAuth 地址不能替代 MCP 地址。
- Claude Code 官方手册提供远程 HTTP/SSE 与本地 stdio 两种配置方式，团队 MCP 服务器属于远程端点，应使用远程 HTTP/SSE 配置。
- 认证支持 OAuth 与手工 Token，手工 Token 可经 X-ONES-MCP-Token 或 Authorization Bearer 携带，凭据绑定用户与团队。
- 首次调用选只读的工作项查询详情，以返回字段、工具列表和权限表现作为验收证据；具体连接命令、OAuth 回调与工具权限端到端表现需在目标环境实测。
先分清两端：Claude Code 管客户端，ONES MCP 管服务端
核对接入前，先把两端的职责和数据方向分开，后续每一步才有明确的检查对象。Claude Code 是发起连接的一方，负责保存 MCP 服务配置、发起请求并展示返回结果；ONES MCP 是提供服务的一方，负责校验凭据、按授权范围返回数据。国内官网已将 Claude Code 列为 MCP 客户端之一，这属于能力说明，具体配置与兼容性仍需在客户端侧验证。
| 维度 | Claude Code（客户端） | ONES MCP（服务端） |
|---|---|---|
| 职责 | 通过 CLI 配置和管理 MCP 服务，可用 /mcp 等入口检查连接与认证状态 | 接受兼容客户端的授权请求，按授权范围返回或变更 ONES 数据 |
| 提供什么 | 传输方式选择、凭据携带方式、调用发起 | 团队 MCP 服务器地址（路径为 /mcp）、OAuth 与手工 Token 认证 |
| 数据方向 | 发起请求，接收结果 | 按授权范围返回工作项、知识库、工时等数据 |
| 核对重点 | 配置的地址、传输、凭据是否与服务端要求一致 | 凭据是否有效、用户与团队权限是否覆盖目标对象 |
把这张表作为核对底稿：出现问题时先判断属于客户端配置还是服务端授权，再进入对应章节，避免在两端之间反复试错。
核对传输方式：端点地址与协议必须匹配
传输方式核对可以归纳为三项：地址来源正确、路径为 /mcp、协议类型与端点一致。三项中任何一项不符，连接都会在建立阶段失败，与后面的认证和权限无关。
地址从哪里取
团队 MCP 服务器地址从 ONES 个人中心的已授权 MCP 客户端页面复制，服务端路径为 /mcp。OAuth 地址不能替代 MCP 地址，这是最常见的核对失败点之一：两个地址外观相近，但用途不同，把 OAuth 地址填入 MCP 配置会导致连接无法建立。
协议怎么选
Claude Code 官方手册提供远程 HTTP/SSE 和本地 stdio 两种配置方式。选择依据是 ONES 端点的实际协议：团队 MCP 服务器地址属于远程服务，应使用远程 HTTP/SSE 方式；stdio 方式适用于由本地进程启动的服务，与远程端点不是同一类配置。实际命令需与 ONES 地址、传输和授权方式匹配，国内详细配置页没有独立的 Claude Code 教程，命令应按端点协议验证，不照搬其他客户端示例。
| 核对项 | 正确做法 | 常见错误 |
|---|---|---|
| 地址来源 | 个人中心已授权 MCP 客户端页面复制 | 使用 OAuth 地址或其他页面地址 |
| 路径 | 确认包含 /mcp | 地址被截断或补了多余路径 |
| 协议类型 | 远程端点用 HTTP/SSE，与地址协议一致 | 对远程地址套用 stdio 配置 |
核对认证：OAuth 与手工 Token 的选择与携带
ONES MCP 支持 OAuth 和手工 Token 两种认证方式，凭据通过 ONES 提供的管理入口获取，并绑定用户与团队。选择哪种方式，取决于客户端配置的便利性与团队对凭据管理的约定；两种方式不应在同一连接中混用。
两种方式的差异
| 认证方式 | 凭据来源 | 携带方式 | 核对要点 |
|---|---|---|---|
| OAuth | ONES 管理入口授权流程 | 由客户端按 OAuth 流程处理 | 回调环节的端到端表现需在目标环境确认 |
| 手工 Token | ONES 管理入口生成，绑定用户与团队 | X-ONES-MCP-Token 或 Authorization Bearer | 凭据类型与携带头必须匹配 |
手工 Token 的两种携带头对应不同的配置写法，核对时确认客户端实际发送的是哪一种，并与生成凭据时的说明保持一致。认证状态可在 Claude Code 侧通过 /mcp 等入口检查，先确认状态正常，再发起业务调用。OAuth 回调的端到端验证属于资料核验缺口，需要在目标环境实际走一遍授权流程并记录结果，不能仅凭配置完成就判定认证可用。
首次业务调用：用一次只读查询验证连通与权限
首次调用建议选择只读的工作项查询详情，避免一开始就触发创建或状态变更。只读查询能同时验证三件事：连接是否建立、认证是否生效、当前用户对目标对象是否有读取权限。
调用前先确认工具发现结果
连接建立后，先看客户端列出的工具列表。工具数量以连接后的工具发现结果为准，手册与官网公布的数量不完全一致，实际列表取决于团队与授权，因此不设固定数量预期。工具出现在列表中，只说明该工具对当前身份可见，不保证能操作任意对象。
观察点与结果解读
| 观察点 | 正常表现 | 异常时的初步判断 |
|---|---|---|
| 连接状态 | 客户端显示已连接 | 回到传输方式章节核对地址与协议 |
| 认证状态 | /mcp 等入口显示认证正常 | 核对凭据类型与携带头 |
| 工具列表 | 出现工作项查询相关工具 | 确认授权范围与团队能力 |
| 查询结果 | 返回目标工作项的详情字段 | 区分对象不存在与权限不足 |
部分相似工作项和知识检索工具依赖 Assistant 及可用的嵌入模型或检索能力，连接成功不代表这些语义能力立即可用。首次验证优先使用按标识查询详情的工具，把语义检索类工具留到基础连通确认之后再测。
异常与重复处理：失败时按层排查
失败时按连接层、认证层、权限层依次排查，每层只回答一个问题，避免同时改动多处配置导致无法定位原因。
分层排查顺序
- 连接层：核对地址是否为 /mcp 路径，传输方式与端点协议是否一致。此层失败通常表现为无法建立连接或连接立即断开。
- 认证层：核对凭据类型与携带头是否匹配，OAuth 与手工 Token 不混用。此层失败通常表现为连接建立后被拒绝。
- 权限层：工具可见但操作失败时，回到授权范围、用户权限、许可与团队能力逐项确认。此层失败通常表现为特定对象或特定操作被拒绝，而其他调用正常。
重复调用的处理原则
创建与更新类操作在重试前先查询确认是否已生效，避免因超时或返回不明确而重复写入。所读 MCP 概述明确暂不支持删除操作，这一限制只针对该 MCP 服务，不代表 REST API 也无删除能力；涉及清理数据的场景需要在接入方案之外单独安排。变更工作项状态应使用工作流工具，并满足相应权限和必填规则。
可验证结果：接入完成的判定标准
接入是否完成，以可逐项核对的证据判定，而不是以配置填写完毕为准。下表把验收项分为已证实能力与待验证项两栏，前者可依据手册核对，后者必须在目标环境实测后记录。
| 验收项 | 判定标准 | 类别 |
|---|---|---|
| 端点地址 | 来自个人中心已授权 MCP 客户端页面，路径为 /mcp | 已证实 |
| 传输方式 | 与端点协议一致，远程端点使用 HTTP/SSE 配置 | 已证实 |
| 认证状态 | OAuth 或手工 Token 配置完成，/mcp 等入口显示正常 | 已证实 |
| 首次只读调用 | 工作项查询详情返回预期字段 | 已证实 |
| 业务能力范围 | 工作项查询详情、创建与更新、评论、执行工作流；知识空间/页面查询与创建、工时相关操作 | 已证实，受权限与许可约束 |
| 具体连接命令 | 在目标环境按端点协议验证并记录 | 待验证 |
| OAuth 回调 | 完整走通授权流程并记录结果 | 待验证 |
| 工具权限端到端表现 | 按角色分别验证可见工具与实际可操作对象 | 待验证 |
适用边界为国内版公有云产品手册范围，私有部署按文内条件确认；本文未进行目标环境实测，历史版本信息不作为当前兼容承诺。验收记录建议保留端点地址、传输方式、认证方式、首次调用对象与返回结果，以及待验证项的实际测试结论，便于后续排查和交接。
常见问题
团队 MCP 服务器地址和 OAuth 地址看起来很像，填错会有什么表现？
把 OAuth 地址填入 MCP 配置，连接会在建立阶段失败，表现为无法连接或连接立即断开，与认证和权限无关。核对时确认地址来自个人中心的已授权 MCP 客户端页面，且路径为 /mcp。出现这类失败先回到传输层检查，不要先去改凭据。
手工 Token 的两种携带头可以混用吗？
不建议混用。手工 Token 可通过 X-ONES-MCP-Token 或 Authorization Bearer 携带，核对时确认客户端实际发送的是哪一种，并与生成凭据时的说明保持一致。同一连接中同时配置 OAuth 与手工 Token 也会让排查失去参照，认证失败时先确认凭据类型与携带头是否匹配。
工具出现在列表里，为什么调用某个工作项还是失败？
工具可见只说明该工具对当前身份可见。可见工具及可操作数据受授权范围、用户权限、许可和团队能力共同限制，工具出现在列表中不保证能操作任意对象。遇到特定对象或特定操作被拒绝、而其他调用正常时，回到授权范围、用户权限、许可与团队能力逐项确认。
首次验证为什么建议用只读查询，而不是直接创建工作项？
只读查询能同时验证连接、认证和读取权限三件事，且不会产生副作用。创建工作项属于写入操作，一旦超时或返回不明确，需要先查询确认是否已生效再决定是否重试，验证成本更高。基础连通确认之后，再按需测试创建、更新、评论与工作流执行等能力。
语义检索类工具连接成功后就能直接用吗？
不一定。部分相似工作项和知识检索工具依赖 Assistant 及可用的嵌入模型或检索能力，连接成功不代表这些语义能力立即可用。首次验证优先使用按标识查询详情的工具，把语义检索类工具留到基础连通确认之后再测，并记录实际结果。
官方参考资料
- MCP 服务概述（ONES）
- ONES Assistant 产品页（ONES）
- Connect Claude Code to tools via MCP（Anthropic）
