MCP 服务概述
什么是 MCP
MCP（Model Context Protocol）用于连接 AI 应用与外部数据和工具。ONES MCP 服务让支持相应连接与认证方式的客户端，以当前用户的身份查询和操作 ONES 数据。
ONES 公有云版本注册了 66 个 MCP 工具。覆盖项目管理、知识库、测试管理、账号与通知、附件读取。实际返回给客户端的工具还取决于授权方式、授权范围和团队能力；业务数据访问继续受 ONES 用户权限限制。
获取 MCP 服务器地址
在 ONES 的个人中心 > 已授权 MCP 客户端页面查看并复制团队的 MCP 服务器地址，将完整地址填入客户端。服务端 MCP 端点为 /mcp，不要将 OAuth 授权地址或内部管理接口作为 MCP 服务器地址。
授权与连接方式
当前支持 OAuth 授权和手工 Token 授权两种方式，均绑定用户、团队和组织身份。
| 对比项 | OAuth 授权 | 手工 Token 授权 |
|---|---|---|
| 适用客户端 | 支持 ONES MCP OAuth 流程的客户端 | 支持设置请求头或 Bearer Token 的客户端 |
| 获取凭据 | 在浏览器完成授权，由客户端交换访问令牌 | 在 ONES 支持的管理入口创建 Token，并配置到客户端 |
| 请求携带方式 | Authorization: Bearer <OAuth access token> | X-ONES-MCP-Token: <manual token>，也支持 Authorization: Bearer <manual token> |
| 续期方式 | 支持使用 Refresh Token 刷新访问令牌 | 不提供 Refresh Token，按设置的有效期失效 |
| 授权范围 | 创建、更新按 scope 校验；读取存在下文说明的例外 | 读取、创建、更新均按 scope 校验 |
| 删除操作 | 暂不支持 | 暂不支持 |
方式一：OAuth 授权
- 在 MCP 客户端中配置 ONES MCP 服务器地址，发起连接。
- 客户端引导你进入 ONES 授权页面。核对实际客户端名称、个人身份和生效团队；客户端名称不固定为原文中的 “MCP CLI Proxy”。
- 按使用需要选择授权范围并确认授权。
- 客户端完成授权码交换后，使用访问令牌连接 MCP 服务。
方式二：手工 Token 授权
对于不支持浏览器 OAuth 跳转、但支持自定义请求头或 Bearer Token 的客户端，可以手动配置 Token。
- 在 ONES 提供的 MCP Token 管理入口创建 Token，设置名称、有效期和所需授权范围，并确认绑定的团队。
- 获取生成的 Token，将团队 MCP 服务器地址填入客户端。
- 根据客户端支持的方式，选择以下一种请求头配置。
- 连接后获取工具列表，检查所需工具是否出现。
Bearer 方式：
Authorization: Bearer <你创建的 MCP Token>
授权范围与可用能力
操作:资源类别:资源名称
| 资源 scope | 含义 | 工具涉及的操作 |
|---|---|---|
project:project | 项目、迭代及项目相关查询 | read、create、update |
project:issue | 工作项及附件内容读取 | read、create、update |
project:issueType | 工作项类型、状态与层级配置 | read |
project:issueField | 工作项字段与选项 | read |
project:issueComment | 工作项评论 | read、create、update |
project:workhour | 工时模式、工时记录与预估 | read、create、update |
wiki:space | 知识空间及页面目录 | read、create |
wiki:page | 知识库页面、内容检索和附件文本 | read、create |
testcase:library | 测试用例库及模块 | read、create、update |
testcase:testcase | 测试用例 | read、create、update |
account:user | 成员、当前用户及通知 | read |
docs:search | ONES 官方文档搜索 | read |
例如，创建项目、创建工作项、发表评论和新增工时分别对应 create:project:project、create:project:issue、create:project:issueComment 和 create:project:workhour。创建知识空间还需要 create:wiki:space。
管理已授权客户端与 Token
OAuth 授权后，可通过个人中心的授权管理入口查看客户端名称、生效团队、授权范围、创建时间与上次访问时间，并修改授权或取消授权。
手工 Token 单独管理，支持查看、修改名称、有效期和授权范围，以及撤销。撤销后，后续认证无法再使用该凭据。
“上次访问时间”表示认证访问记录，不等同于最后一次成功执行某个工具的时间。
可用工具一览
表中 scope 为完整授权标识；标记 † 的工具依赖团队开启 Assistant 且具备可用的嵌入模型／检索能力，条件不满足时不会向客户端展示，也不能调用。
项目管理：工作项（19 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
create_new_issue | 创建工作项，如任务、缺陷、需求等。 | create:project:issue |
execute_issue_workflow | 执行工作项的可用工作流，变更工作项状态。 | update:project:issue |
find_similar_issues | 根据指定工作项的内容查找相似工作项。† | read:project:issue |
get_issue_activities | 获取工作项动态，包括字段变更、评论和状态变更等。 | read:project:issue |
get_issue_code_info | 获取工作项关联的代码提交、分支和 Pull Request 信息。 | read:project:issue |
get_issue_human_readable_keys | 批量获取工作项的可读编号。 | read:project:issue |
get_issue_details | 获取工作项详情。 | read:project:issue |
get_issue_executable_workflows | 获取指定工作项当前可执行的工作流。 | read:project:issue |
get_issue_fields | 获取工作项字段、字段类型、必填规则等信息。 | read:project:issueField |
get_issue_status | 获取工作项状态信息。 | read:project:issueType |
get_issue_type_hierarchy_configs | 获取工作项类型的层级及父子关系配置。 | read:project:issueType |
get_list_of_issue_comments | 获取工作项评论列表。 | read:project:issueComment |
get_onesql_grammar_help | 获取 ONESQL 语法及查询规则；执行 ONESQL 查询前应先调用。 | read:project:issue |
post_issue_comment | 发表工作项评论，支持提及成员。 | create:project:issueComment |
query_issues_by_onesql | 使用 ONESQL 查询工作项。 | read:project:issue |
search_for_issue_field_options | 按关键字查找指定工作项字段的可选项。 | read:project:issueField |
search_for_issue_types | 按关键字查找工作项类型。 | read:project:issueType |
update_issue | 更新工作项指定字段；状态变更使用工作流工具。 | update:project:issue |
update_issue_comment | 修改工作项评论。 | update:project:issueComment |
项目管理：项目、迭代与相关对象（12 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
add_project_members | 向项目添加成员。 | update:project:project |
create_new_project | 创建项目。 | create:project:project |
create_sprint | 创建迭代。 | create:project:project |
get_project_details_by_project_id | 根据项目 ID 获取项目详情。 | read:project:project |
get_sprint_details | 获取迭代详情。 | read:project:project |
search_for_epics | 按名称关键字查找史诗，可限定项目。 | read:project:project |
search_for_modules | 按名称关键字查找项目模块，可限定项目。 | read:project:project |
search_for_projects | 按项目名称及其他条件查找项目。 | read:project:project |
search_for_releases | 查找发布版本，可限定项目。 | read:project:project |
search_for_sprints | 按名称关键字查找迭代，可限定项目。 | read:project:project |
update_project_by_project_id | 更新项目基本信息。 | update:project:project |
update_sprint | 更新迭代信息。 | update:project:project |
项目管理：工时（11 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
get_manhour_mode | 获取当前团队的工时模式：简单模式或汇总模式。 | read:project:workhour |
get_manhour_list_in_simple_mode | 获取工作项的工时记录列表（简单模式）。 | read:project:workhour |
set_manhour_estimated_in_simple_mode | 设置工作项预估工时（简单模式）。 | update:project:workhour |
set_manhour_remaining_in_simple_mode | 设置工作项剩余工时（简单模式）。 | update:project:workhour |
add_workhour_in_simple_mode | 新增实际工时登记（简单模式）。 | create:project:workhour |
update_workhour_in_simple_mode | 更新已登记实际工时（简单模式）。 | update:project:workhour |
get_manhour_list_in_summary_mode | 获取工作项的工时记录列表（汇总模式）。 | read:project:workhour |
add_manhour_estimated_in_summary_mode | 新增预估工时记录（汇总模式）。 | create:project:workhour |
update_manhour_estimated_in_summary_mode | 更新预估工时记录（汇总模式）。 | update:project:workhour |
add_workhour_in_summary_mode | 新增实际工时登记（汇总模式）。 | create:project:workhour |
update_workhour_in_summary_mode | 更新已登记实际工时（汇总模式）。 | update:project:workhour |
知识库（11 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
create_space | 创建知识空间（页面组）；需要创建权限及可用的 Wiki 许可。 | create:wiki:space |
get_space_details | 获取知识空间详情，包括首页 ID。 | read:wiki:space |
get_list_of_space_pages | 获取知识空间中的页面列表及父子关系信息。 | read:wiki:space |
search_pages_by_title | 按标题关键字搜索页面，可限定知识空间。 | read:wiki:space |
search_for_spaces | 按关键字查找知识空间。 | read:wiki:space |
create_page | 创建知识库页面。 | create:wiki:page |
get_page_details | 获取知识库页面详情。 | read:wiki:page |
get_page_changes | 获取指定时间之后的页面变更及按用户分组的编辑操作；是否支持取决于页面类型。 | read:wiki:page |
get_page_attachment_text | 读取知识库附件已转换的文本或已有转写内容。† | read:wiki:page |
get_favorite_or_watch_pages | 获取当前用户收藏或关注的页面。 | read:wiki:page |
search_for_references_in_wiki | 按问题检索知识库相关页面与附件内容，可限定知识空间或页面。† | read:wiki:page |
测试管理（9 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
create_module_in_testcase_library | 在测试用例库中创建模块。 | create:testcase:library |
create_new_testcase_in_library | 在测试用例库中创建测试用例。 | create:testcase:testcase |
get_testcase_details | 获取测试用例详情。 | read:testcase:testcase |
get_testcase_library_fields | 获取测试用例库的字段配置。 | read:testcase:library |
search_for_modules_in_testcase_library | 按名称关键字查找测试用例库模块。 | read:testcase:library |
search_for_testcases_in_library | 在测试用例库中查找测试用例。 | read:testcase:testcase |
search_for_testcase_libraries | 按名称及其他条件查找测试用例库。 | read:testcase:library |
update_module_in_testcase_library | 更新测试用例库模块名称。 | update:testcase:library |
update_testcase | 更新测试用例。 | update:testcase:testcase |
账号与通知（3 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
search_for_users | 按姓名、邮箱或工号等关键字搜索成员。 | read:account:user |
who_am_i | 获取当前调用身份的信息，可用于确定用户时区。 | read:account:user |
get_user_notices | 获取指定时间之后的用户通知。 | read:account:user |
附件（1 个）
| 工具名称 | 说明 | 授权 scope |
|---|---|---|
read_attachment_content | 根据资源 ID 读取附件文本或图片供模型理解，不保存文件到本地。 | read:project:issue |
使用限制与说明
- 工时模式：先调用
get_manhour_mode确认团队使用简单模式还是汇总模式，再选择对应工具。 - 知识库创建：
create_space创建知识空间后返回首页 ID，可作为create_page的父页面 ID 使用； - 附件内容：
read_attachment_content返回模型可读的文本或图片，不将原始文件下载到本地，不返回视频、音频或压缩包等二进制内容；文本上限为 128 KiB，图片上限为 10 MiB。知识库附件已转换的文本通过get_page_attachment_text获取。 - 权限与可见性：工具出现在列表中不等于能操作任意业务对象；具体执行仍可能因业务权限、许可、参数或环境能力不足而失败。