版本：7.33

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 获取。
权限与可见性：工具出现在列表中不等于能操作任意业务对象；具体执行仍可能因业务权限、许可、参数或环境能力不足而失败。

什么是 MCP​

获取 MCP 服务器地址​

授权与连接方式​

方式一：OAuth 授权​

方式二：手工 Token 授权​

授权范围与可用能力​

管理已授权客户端与 Token​

可用工具一览​

项目管理：工作项（19 个）​

项目管理：项目、迭代与相关对象（12 个）​

项目管理：工时（11 个）​

知识库（11 个）​

测试管理（9 个）​

账号与通知（3 个）​

附件（1 个）​

使用限制与说明​