MCP 工具参考

HyperAI MCP 服务器提供 34 个工具,分为五个功能组。所有工具在 OAuth 登录后以你自己的账号身份执行,结果仅限于你有权访问的容器、项目与数据集。列表类工具每页返回 30 条。

通常你不需要直接调用这些工具——AI 助手会根据你的要求自行选择。本页作为参考,帮助你了解助手能做什么、不能做什么。

User(账户)

用于查询自己账户的工具——档案、配额、账单、用量与订阅,以及管理个人访问令牌。这些工具始终作用于当前登录账号,不接受 username 参数。

user_get_profile

获取你的账户档案：用户名、显示名称、邮箱、注册时间、角色、会员状态、余额,以及所属组织。组织的 ID(而非显示名称)即 compute 与 dataset 工具中 username 参数可接受的值——既可用于列出组织资源(如 compute_list_jobs),也可用于在组织名下创建与管理资源(如 compute_create_job)。可用于验证连接。组织的能力标志、席位配额与成员列表请使用 org_get 与 org_list_members 工具查询。

无参数。

user_get_quota

获取你的存储配额(已用 / 总量 / 剩余)、各资源型号的预付算力时长,以及账户限制(如容器、GPU、数据集、项目的数量上限)。

配额是预付余额,不是能力上限——某个资源的剩余时长为 0 并不代表它不可用;按量付费的使用仍会从账户余额中扣费。

无参数。

user_list_transactions

列出账单流水——充值、扣费、订阅续费、退款与转账,按时间从新到旧排序。每笔金额都带有各自的币种。

参数：

• type — 按方向筛选：recharge(充值、赠送、代金券入账)、spend(扣费)、refund(退款)、transfer(账户间转账)或 all(默认)
• page — 页码

user_list_usages

列出资源使用记录,按时间从新到旧排序。计算类记录带有使用时长;serving 类记录按(结束时间 − 开始时间)× 副本数计费;存储类记录带有计入存储配额的容量变化。

参数：

• page — 页码

user_list_subscriptions

列出你所有类别的订阅——会员、存储扩容、预付算力、一次性永久算力与组织席位,含套餐、每周期价格、有效期与自动续费状态。处于生效中且开启自动续费的订阅会在每个周期结束时自动扣费。

取消订阅只能在 HyperAI 控制台操作,本工具不支持。

无参数。

user_get_spend_analysis_guide

返回账户消费分析指南。助手在回答消费类问题("余额为什么变少了"、"我的钱花在哪了")前应先阅读该指南,以便先通过其他账户工具收集完整数据。

无参数。

user_list_personal_access_tokens

列出你的个人访问令牌(PAT)——长期有效的 API 凭据,含名称、创建与过期时间、最近使用时间。列表中永远不包含令牌明文：明文只在创建令牌时显示一次。空列表并不代表从未创建过令牌(已吊销的令牌会被隐藏);列表中的令牌也不一定可用——过期令牌仍会留在列表里,请自行核对 expiresAt。

无参数。

user_create_personal_access_token

为你自己的账号创建个人访问令牌。PAT 不受改密码或退出登录的影响,只有被吊销或过期后才会失效。

参数：

• name — 令牌标签,最多 30 个字符;仅用于识别,不参与鉴权
• expires_at — 可选,过期时间,ISO 8601 UTC 格式(如 2026-11-15T00:00:00Z),必须是未来时刻。省略时默认自创建起 90 天。

user_revoke_personal_access_token

吊销一个个人访问令牌。吊销后,工具会重新读取列表以确认令牌已失效。

参数：

• id — 令牌 ID,来自 user_list_personal_access_tokens,不是令牌明文
• confirm_name — 必须与令牌的当前名称完全一致

Compute(算力容器)

用于操作算力容器与项目的工具——与控制台中算力容器部分是同一批对象。操作特定容器或项目的工具都接受可选的 username 参数：传入组织 ID 即可操作该组织的资源,且同一容器的每次后续调用都要传相同的值。

compute_list_jobs

列出算力容器,按创建时间从新到旧排序。

参数：

• username — 可选,你所属的组织(所属组织可通过 user_get_profile 查看);省略则列出个人账号下的容器
• status — running / succeeded / failed / cancelled / all(默认 all)
• q — 按容器名称子串匹配
• page — 页码

compute_list_projects

列出项目。

参数：

• username — 可选,你所属的组织(所属组织可通过 user_get_profile 查看)
• q — 按项目名称子串匹配
• page — 页码

compute_list_resources

列出可用的算力资源型号(GPU/CPU),含规格、余额是否足以使用、当前负载情况。

参数：

• username — 可选

compute_list_plans

列出计费方案：按量付费与包时套餐(含时长与价格)。

参数：

• resource — 可选,来自 compute_list_resources 的资源名称

compute_list_runtimes

列出可用的容器运行时环境(镜像),不含已弃用的版本。

参数：

• username — 可选

compute_get_job

获取容器的完整详情,包括访问地址。密钥值会被脱敏。

参数：

• job_id_or_url — 容器 ID 或控制台容器页面 URL
• username — 可选,拥有该容器的组织;省略则查询个人账号下的容器

compute_get_job_metrics

获取容器的系统指标与自定义指标摘要(最新值 / 最小 / 最大 / 平均)。

参数：

• job_id — 容器 ID

compute_get_project

获取项目详情及其容器执行历史。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• status — 筛选执行历史：running / succeeded / failed / cancelled / all
• page — 页码
• username — 可选,拥有该项目的组织;省略则查询个人账号下的项目

compute_get_job_readme

读取容器的 README,返回已渲染的 HTML。

参数：

• job_id_or_url — 容器 ID、项目 ID 或控制台 URL

compute_get_job_notebook

读取容器的 Notebook 内容。

参数：

• job_id_or_url — 容器 ID、项目 ID 或控制台 URL

compute_get_create_job_guide

返回创建容器的推荐流程说明(计费、数据绑定、环境变量、端口、在组织下创建)。助手应在调用 compute_create_job 前先阅读。

无参数。

compute_create_job

创建新的工作空间容器。

参数：

• resource — 必填,来自 compute_list_resources 的资源名称
• runtime — 必填,来自 compute_list_runtimes 的运行时名称
• project_id / new_project_name — 二选一：在已有项目中创建,或新建项目
• description — 可选,容器描述
• plan_id — 可选,来自 compute_list_plans 的包时套餐;省略则按量付费
• auto_renew — 包时套餐是否自动续费(默认 true)
• idle_timeout_minutes — 闲置自动停止时间(默认 30,0 表示禁用)
• env — 环境变量,{name, value, secret} 列表
• data_bindings — 要挂载的数据,{source, mount_path, writable} 列表
• ports — 自定义端口映射,{port, name} 列表
• username — 可选,组织 ID(而非显示名称),在该组织名下创建容器。容器费用记入组织余额,且该容器的每次后续调用都必须传相同的 username;省略则在个人账号下创建

该工具遵循与控制台一致的规则：

• 数据绑定挂载在 /input0 到 /input4(只读来源,如数据集和模型)与 /output(只能绑定形如 <owner>/jobs/<job-id>/output 的历史容器输出)。参见数据绑定。
• 环境变量不能使用保留前缀 OPENBAYES_,名称中含 TOKEN / SECRET / KEY / PASSWORD 的必须标记为密钥。参见环境变量。
• 8080 端口为容器内置服务保留,不能映射。参见自定义端口映射。
• 所选资源必须在当前余额下可用且未满载,所选计费方案必须属于该资源。

compute_stop_job

停止正在运行的容器。

参数：

• job_id — 必须是准确的容器 ID,不接受 URL
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

compute_restart_workspace

以先前的配置重启已停止的工作空间容器。

参数：

• job_id — 容器 ID
• username — 可选,拥有该工作空间的组织——重启费用记入组织余额;省略则操作个人账号下的容器

compute_update_project

更新项目设置：名称、描述、闲置超时与标签。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• name — 可选,新名称
• description — 可选,新描述
• idle_timeout_minutes — 可选,作用于整个项目,0 表示禁用
• add_tags / remove_tags — 可选,标签列表;标签会与平台标签目录校验
• username — 可选,拥有该项目的组织;省略则操作个人账号下的项目

compute_update_job_ports

为容器添加或移除自定义端口映射。映射后的端口会获得一个公网可访问的 URL,也就是说开放端口会把监听该端口的服务发布到互联网——助手应在开放端口前与你确认。8080 端口为保留端口,不能映射。

参数：

• job_id — 容器 ID
• add_ports — {port, name} 列表
• remove_ports — 要移除的端口号列表
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

Resources(公共资源)

用于发现平台公共内容的工具。

resources_search_public_projects

搜索公共项目(教程与社区项目),支持按标签筛选。每条结果都带有克隆次数,可作为热度参考;公共项目可以克隆为新容器的起点。

参数：

• q — 搜索关键词
• tags — 用于筛选的标签名称列表
• sort — 结果排序：LAST_ACTIVE_AT_DESC(默认)/ LAST_ACTIVE_AT_ASC / CLONE_COUNT_DESC / CLONE_COUNT_ASC;找最热门的项目用 CLONE_COUNT_DESC
• page — 页码

Dataset(数据集与模型)

用于管理数据集与模型的工具——搜索、查看详情、创建条目、更新元数据与删除。不包括数据上传：上传需在网页控制台或使用 bayes CLI 完成。

dataset_search

一次调用同时搜索自有与公共的数据集和模型。每条结果包含可作为 compute_create_job 中 data_bindings 来源的绑定名称。

参数：

• q — 搜索关键词
• category — dataset / model / all(默认 all)
• username — 可选,在所属组织下搜索而非个人账号
• tags — 用于筛选公共结果的标签名称列表;标签是平台受控词表,需精确匹配
• page — 自有结果的页码
• public_page — 公共结果的页码

dataset_get

一次调用获取数据集或模型的完整详情：元数据、所有者、权限、全部版本,以及所选版本的 README(已渲染的 HTML)。每个版本都带有可作为 compute_create_job 中 data_bindings 来源的绑定名称;顶层容量为全部版本之和。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL;URL 末尾的版本号会被识别
• version — 可选,版本号;优先于 URL 中的版本

dataset_create

创建一个新的空数据集或模型条目——仅包含元数据,没有版本和数据。每次调用都会新建一个条目,请先用 dataset_search 检查是否已存在,避免重复创建。

参数：

• name — 必填,条目名称
• kind — dataset / model(默认 dataset)
• description — 可选,描述
• tags — 可选,标签列表;标签必须是平台标签目录中的现有名称(区分大小写)
• username — 可选,在所属组织下创建而非个人账号

dataset_update

更新数据集或模型的元数据：名称、描述、类别与标签。只传需要修改的字段。组织名下的条目可直接操作——所有者会被自动解析。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL
• name — 可选,新名称
• description — 可选,新描述
• kind — 可选,在 dataset 与 model 之间切换
• add_tags / remove_tags — 可选,标签列表;标签会在写入前与平台标签目录校验

dataset_delete

永久删除数据集或模型,包括所有版本和已上传的全部数据。删除后工具会重新读取该条目以确认删除成功。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL
• confirm_name — 必须与条目当前的名称完全一致

Org(组织)

用于查询所属组织的工具。三个工具均为只读——邀请成员、变更角色与退出组织都需在控制台操作。组织的 ID 可作为 compute 与 dataset 工具的 username 参数使用——既可列出组织资源(compute_list_jobs、dataset_search),也可在组织名下创建与管理资源(compute_create_job、dataset_create)。

org_list

列出你所属的组织,含你在每个组织中的角色(OWNER / MEMBER / PENDING)与该组织下的能力标志(如 canCreateProject、canCreateInvitation)。"在这个组织里能不能做某事"以能力标志为准,而非角色。

无参数。

org_get

获取单个组织的详情：资料(显示名、描述、类型、锁定状态)、席位配额(已用 / 总数 / 剩余),以及你在该组织中的能力标志。

参数：

• org_id — 组织 ID,而非显示名

org_list_members

列出组织成员,每页 30 条：用户名、显示名、角色与加入时间,并标明你是否可以移除某个成员或变更其角色。角色为 PENDING 的行是尚未接受的邀请。

参数：

• org_id — 组织 ID
• page — 页码