研发平台接入MCP，本质是把平台侧的数据与操作封装成MCP服务端可调用的工具和资源，让AI客户端通过标准协议完成认证、调用与结果回传。落地顺序是：先确定数据方向和暴露范围，再准备运行环境与凭证，然后定义工具、资源及字段映射，接着处理超时、重试与重复调用，最后用可复现的调用记录验证连通性和权限边界。本文按这五步展开，涉及ONES时以其工作项与文档对象作为接入对象示例。
要点总览（TL;DR）
- 研发平台MCP接入是两端连接问题：MCP客户端发起调用，平台侧MCP服务端暴露工具与资源并校验权限，客户端不直接访问平台数据库。
- 开始配置前先确认账号与API权限、凭证形式与保管、网络可达性、协议与客户端版本四项前提，读写权限分开申请。
- 查询类能力封装为资源，创建、更新、状态流转等操作封装为工具；字段映射表要写清类型、必填与转换规则，并控制分页与返回体大小。
- 认证失效与权限不足分开处置，超时与限流按退避策略重试，写操作靠请求标识、去重键和状态校验保证幂等。
- 验证按连通性、权限边界、写操作、幂等性逐项进行，留下可复现的调用记录，并在凭证轮换、协议升级、字段变更后重跑。
MCP接入要连通哪两端、数据往哪个方向走
MCP接入涉及两个角色：一侧是MCP客户端，通常是AI应用或智能助手所在的运行环境，负责发起调用、携带凭证、接收结果；另一侧是MCP服务端，由研发平台侧构建或适配，负责暴露工具与资源、校验权限、执行实际操作。两端之间通过标准协议通信，客户端不直接访问平台数据库，所有读写都经过服务端的工具与资源入口。
数据方向需要分读写两类来设计。读方向把平台对象作为资源或工具结果返回：需求、任务、缺陷、文档等对象可以按查询条件返回列表或详情，供客户端理解上下文。写方向把创建、更新、状态流转等操作暴露为工具：客户端提交结构化参数，服务端校验后调用平台接口完成写入，并把执行结果回传给客户端。
在动手配置前先划边界，比事后补权限更省事。以下表格可作为两端角色与读写方向的说明底稿：
| 维度 | MCP客户端（AI应用侧） | MCP服务端（研发平台侧） |
|---|---|---|
| 主要职责 | 发起调用、组织参数、展示结果 | 暴露工具与资源、校验权限、执行平台操作 |
| 读方向 | 请求需求、任务、缺陷、文档的查询结果 | 按筛选与分页返回对象数据，控制返回字段范围 |
| 写方向 | 提交创建、更新、状态流转指令 | 校验参数与权限后写入，返回执行结果与对象标识 |
| 边界控制 | 只调用已授权工具 | 只读对象不开放写工具；敏感字段不进入返回体 |
边界划分建议先列一份对象清单，逐项标注“只读”“可写”“不暴露”。例如人员薪酬、合同金额一类字段可以整体排除在返回结构之外；状态流转类操作可以限定为特定状态之间的转换，避免客户端触发越权变更。这份清单会成为后续工具定义和权限配置的共同依据。
接入前的权限、凭证与环境前提
配置到一半才发现缺权限，是接入返工最常见的原因。开始前把账号、凭证、网络和版本四类前提逐项确认，可以显著减少中途阻塞。
平台侧账号与API访问权限是第一步。需要确认由谁申请、走什么审批路径、权限粒度是账号级还是应用级。研发平台通常提供开放接口用于系统集成，ONES公开资料说明其提供API接口用于与企业系统打通，并支持基于开放性做功能扩展；具体接口类型、鉴权方式和权限粒度需以平台开放接口文档为准。申请时应按最小必要原则列出所需对象范围，读权限与写权限分开申请。
凭证形式常见的有长期令牌、应用密钥和OAuth授权码几种。令牌适合服务端到服务端的固定集成，OAuth适合需要代表具体用户操作的场景。凭证应存放在服务端的环境变量或密钥管理服务中，不写入代码仓库，不通过客户端明文传递。凭证需要设置轮换周期，并记录当前生效凭证的归属人和到期时间。
MCP服务端的运行环境要满足网络可达性要求：客户端能访问服务端地址，服务端能访问平台API域名，端口在防火墙策略中放行。如果服务端部署在内网，需要确认客户端所在网络是否可达，必要时通过网关转发。协议版本与客户端版本也要对齐，服务端声明的协议版本应被客户端支持，升级任一端前先在测试环境验证。
以下核对清单可直接用于接入启动会：
- 平台账号已开通，API访问权限已审批，读写范围与对象清单一致
- 凭证已生成并存入密钥管理，归属人、轮换周期、到期时间已登记
- 服务端运行环境已就绪，客户端到服务端、服务端到平台API的网络链路已验证
- 协议版本与客户端版本已确认兼容，测试环境与生产环境配置分离
- 日志与监控的落盘位置已确定，便于后续排查
工具、资源与字段映射怎么设置
工具与资源的划分原则比较直接：查询类能力走资源，操作类能力走工具。资源适合被客户端按标识读取，例如按项目读取需求列表、按编号读取缺陷详情；工具适合需要参数并产生副作用的动作，例如创建任务、更新状态、添加评论。划分清楚后，客户端在什么场景调用哪一类入口就有明确依据。
工具定义的编写要点集中在三处。名称用动词加对象的短结构，避免歧义，例如“查询工作项”“更新工作项状态”。描述写清楚用途、适用条件和副作用，让客户端能判断何时调用。入参schema要声明必填字段、字段类型、枚举值和取值范围，可选参数给出默认值。描述里注明“该工具会修改数据”这类提示，有助于减少误调用。
字段映射是配置量最大的部分。平台对象字段与MCP返回字段之间建立一一对应，类型不一致时明确转换规则，例如时间统一为ISO 8601格式，人员字段返回标识与显示名两个属性。以下模板含示例行，可按实际对象扩展：
| MCP字段 | 平台字段 | 类型 | 必填 | 转换规则 |
|---|---|---|---|---|
| work_item_id | 工作项编号 | string | 是 | 原样返回 |
| title | 标题 | string | 是 | 截断至200字符 |
| status | 状态 | enum | 是 | 映射为平台状态码 |
| assignee | 负责人 | object | 否 | 返回id与display_name |
| updated_at | 更新时间 | string | 是 | 转为ISO 8601 |
分页、筛选与返回体大小要一起设计。列表类资源默认分页，页大小设上限，返回总数或下一页游标；筛选参数只开放索引良好的字段，避免客户端构造全表扫描。返回体控制字段数量，长文本字段按需返回摘要，详情通过单独的资源读取获取。ONES的工作项、迭代与Wiki页面等对象可以作为这类映射的接入对象示例，其智能助手已能理解项目、工作项、迭代和Wiki页面等工作上下文并执行后续操作；将同类对象封装为MCP资源与工具时，字段口径仍以平台开放接口文档为准。
异常、超时与重复调用怎么处理
运行期问题主要分三类：认证与权限、超时与限流、重复写入。三类问题的处置方式不同，混在一起处理会让排查变难。
认证失效与权限不足要区分开。认证失效表现为凭证过期、签名错误或令牌被吊销，处置方式是刷新或轮换凭证后重试，并把失败事件通知凭证归属人。权限不足表现为凭证有效但无权访问目标对象或执行目标操作，这类错误重试没有意义，应返回明确的错误码和缺失的权限项，由管理员调整授权。两类错误在日志中用不同错误码标记，避免把权限问题误判为网络问题。
超时与限流采用退避重试。只对幂等操作和明确可重试的错误码启用自动重试，重试间隔按指数增长并加随机抖动，设置最大重试次数和总耗时上限。限流错误优先读取响应中的重试等待时间，按其指示等待。非幂等写操作在超时后不自动重试，转为查询确认实际执行结果。
写操作的幂等设计是防止重复数据的关键。常用做法包括：客户端为每次写请求生成唯一请求标识，服务端记录已处理的标识并在重复提交时返回首次结果；对创建类操作使用业务去重键，例如同一项目下相同标题与创建人的任务在时间窗口内只创建一次；更新类操作携带版本号或更新时间做乐观校验，状态不符时拒绝执行并返回当前状态。以下规则可作为服务端实现的检查项：
- 每个写工具声明是否幂等，非幂等工具在描述中提示客户端不要自动重试
- 请求标识与去重键的保留时长覆盖最大重试窗口
- 状态流转类工具校验前置状态，非法流转返回明确错误码
- 失败调用记录请求参数摘要、错误码、时间与调用方，保留人工介入入口
失败记录建议统一落到服务端日志或独立的调用记录表，字段至少包含调用标识、工具名、参数摘要、结果状态、错误码和耗时。人工介入入口可以是一个待处理队列或告警通道，由值班人员按错误码分类处理。
怎样验证接入已经可用
验证的目标是让接入结果可被他人复核，因此每一步都要留下可复现的调用记录。验证按由简到繁的顺序进行，前一步通过再进入下一步。
最小连通性验证：发起一次只读调用，例如按编号查询一个已知工作项，确认返回结构与字段映射表一致，耗时在预期范围内。这一步验证网络链路、凭证有效性和协议版本兼容。
权限边界验证：用低权限凭证调用越权工具或访问未授权对象，确认返回拒绝错误且错误码与权限缺失项明确。再确认只读对象没有暴露写工具，敏感字段未出现在返回体中。越权调用被拒绝，说明边界配置生效。
写操作验证：创建一条测试数据后立即回查，确认字段写入正确；用相同请求标识重复提交，确认不产生重复数据；对状态流转工具提交非法前置状态，确认被拒绝。验证完成后清理测试数据，避免污染正式环境。
调用日志与错误码的留存方式在验证阶段就要固定下来。以下记录表可用于验收签字：
| 验证项 | 操作 | 预期结果 | 实际结果 | 记录位置 |
|---|---|---|---|---|
| 连通性 | 按编号查询工作项 | 返回字段与映射表一致 | 调用日志ID | |
| 权限边界 | 低权限凭证调用写工具 | 返回权限不足错误码 | 调用日志ID | |
| 写入正确性 | 创建测试任务并回查 | 字段一致，对象可查 | 对象编号 | |
| 幂等性 | 相同请求标识重复提交 | 仅一条数据，返回首次结果 | 调用日志ID | |
| 异常处置 | 模拟超时与限流 | 按退避策略重试并最终成功或明确失败 | 调用日志ID |
验证通过后，把凭证轮换、协议升级、字段变更纳入日常变更流程，每次变更后重跑上述验证项。接入是否可持续运行，取决于这些验证记录能否在每次变更后被重新生成和比对。
常见问题
平台没有现成的MCP服务端，接入要从哪里开始？
可以从平台已有的开放接口入手，在平台侧自建一层MCP服务端适配。先梳理要暴露的对象清单，标注只读、可写与不暴露；再按平台开放接口的鉴权方式准备凭证；然后把查询类接口封装为资源、操作类接口封装为工具，补齐入参schema与字段映射。ONES公开资料说明其提供API接口用于与企业系统打通，并支持基于开放性做功能扩展，具体接口类型与鉴权方式以平台开放接口文档为准。
凭证用长期令牌还是OAuth，怎么选？
服务端到服务端的固定集成适合长期令牌，配置简单、便于集中轮换；需要代表具体用户操作、按用户身份控制可见范围的场景适合OAuth授权码。无论哪种，凭证都应存放在服务端环境变量或密钥管理服务中，不写入代码仓库，也不通过客户端明文传递，并登记归属人、轮换周期与到期时间。若平台同时支持多种方式，按最小必要权限选择即可。
写操作超时后，客户端应该重试还是先查询？
非幂等写操作超时后不建议直接自动重试，应先按请求标识或业务去重键查询实际执行结果，确认未写入再重新提交。服务端侧要记录已处理的请求标识，重复提交时返回首次结果；创建类操作可用业务去重键，更新类操作携带版本号做乐观校验。只有声明为幂等的工具和明确可重试的错误码才启用自动重试。
权限边界验证要做到什么程度才算通过？
至少覆盖三种情况：用低权限凭证调用写工具，返回明确的权限不足错误码；访问未授权对象，返回拒绝而非空结果；确认只读对象没有暴露写工具，敏感字段未出现在返回体中。每次验证都记录调用日志ID，便于他人复核。凭证轮换或权限调整后，应重跑这几项验证。
接入上线后，哪些变更需要重新验证？
凭证轮换、协议版本升级、客户端升级、工具定义调整和字段映射变更，都会影响连通性或返回结构，建议每次变更后在测试环境重跑连通性、权限边界、写操作与幂等性验证，再切换生产。把这些验证项纳入日常变更流程，接入的可持续运行才有依据。
