voxel51-agent-setup

用途

本技能把本地 AI 智能体（Claude Code、Cursor 或任何兼容 MCP 的客户端）通过 MCP 连接到 Voxel51 部署。连接完成后，智能体以执行审批的用户本人身份运行，拥有与该用户完全相同的角色和数据集权限，不涉及单独的服务账号或共享凭据。

前提与限制

需要 Voxel51 部署，并由管理员开启远程智能体访问。该能力是 Voxel51 专属功能，位于功能开关之后，默认关闭。自托管部署需先由 Voxel51 客户成功联系人开启。
若使用开源版 FiftyOne，或部署尚未开启该功能，则无法使用；此时应改用随技能集合一同安装的本地 fiftyone-mcp 服务器，它面向本地 FiftyOne 安装，无需下述步骤。
需要部署的网关 URL。Voxel51 Cloud 的主机固定为 app.voxel51.com；自托管需向用户或管理员询问主机名。路径后缀固定为 https://<host>/api/proxy/fiftyone-teams/mcp。
需要一个支持远程 HTTP 服务器与 OAuth 的 MCP 客户端。

使用方式

确认用户使用的是 Voxel51 Cloud 还是自托管，并确认远程智能体访问已开启。
将网关添加为远程 MCP 服务器。Claude Code 命令：

claude mcp add --transport http --scope user voxel51-agent-gateway \
  https://<your-deployment>/api/proxy/fiftyone-teams/mcp \
  --client-id voxel51-agent-mcp

--client-id 为必需参数：该部署的认证服务器不支持动态客户端注册，自行注册的客户端会报错「Incompatible auth server: does not support dynamic client registration」。voxel51-agent-mcp 是所有智能体使用的固定客户端 ID。其他客户端可使用等价配置片段，例如 Claude Desktop / Cursor：

{
  "mcpServers": {
    "voxel51-agent-gateway": {
      "type": "http",
      "url": "https://<your-deployment>/api/proxy/fiftyone-teams/mcp"
    }
  }
}

若客户端配置格式无法显式固定客户端 ID，并出现同样的动态注册错误，则该客户端暂不支持此路径。 3. 添加后需重启智能体或开启新会话，新 MCP 服务器才会在下一会话挂载。 4. 触发连接（例如尝试使用新工具），浏览器会打开一次性 OAuth 同意页面，用户登录并批准即完成连接，无需 API 密钥。

主要能力

连接后提供五个工具：list_operators、get_operator_schema、execute_operator、list_delegated_operations、get_delegated_operation，可访问审批用户账号有权查看和运行的 FiftyOne 算子，权限在每次调用时实时校验。长耗时算子可用 execute_operator(..., delegate=True) 后台运行，检查返回结果的 delegated 字段（并非所有算子都支持），再用 get_delegated_operation 轮询结果。

使用建议

算子目录规模较大（通常数百个，因部署和用户权限而异），多数算子没有文字说明。建议先阅读参考文件而非直接浏览 list_operators：

references/datasets-and-samples.md：数据集生命周期、视图、字段与模式、样本与标签编辑、索引、媒体导入、工作区。
references/analysis-and-labeling.md：brain 方法、嵌入、模型评估、数据质量、自动标注、智能体标注、注释、zoo 模型、工作流、标签模式。
references/delegated-operations.md：后台运行、结果检查、委托运行元数据。
references/agent-tools.md：FiftyOne Agent 自身算子（对话、代码执行、插件/技能编写、记忆）。
references/not-available.md：常见但当前无法通过此方式访问的功能及原因。

参考文件是地图而非模式定义，不重述精确参数。确定算子后，应先调用 get_operator_schema 确认当前参数，再调用 execute_operator。list_operators(dataset_name=...) 会按实时权限过滤，可用于确认某算子对该调用者在当前数据集上是否可用，而非用于浏览。

生成深链

没有 MCP 工具或 FiftyOne SDK 调用可生成可分享的 App URL。需自行用部署主机（非网关路径）拼接：

数据集：https://<host>/dataset/<url-encoded-name>
特定样本：追加 /sample/<sample-id>
特定分组：追加 /group/<group-id>
已保存视图：?view=<saved-view-slug>，仅适用于已保存（有 slug）的视图，无法深链临时筛选视图的原始阶段
活动分组切片：&slice=<slice-name>
一个或多个面板：&panel=<name> 或 &panel=<name1>,<name2>。此参数专为智能体生成链接而构建；底层 open_panel 算子仅限浏览器，无法经 execute_operator 调用，只能放入 URL 使用。

示例（带模型评估面板的样本）：https://<host>/dataset/my-dataset/sample/<sample-id>?panel=model_evaluation_panel_builtin

不要臆造其他查询参数，也不要提供 ?share= 链接。

疑难排查

添加时出现动态客户端注册错误：移除并重新添加服务器，显式指定 --client-id voxel51-agent-mcp。
配对审批被拒并提示缺少权限：审批用户账号缺少 USE_API_KEYS 权限，需管理员授予，属有意设计。
预期算子在 list_operators 中不存在：当前角色或数据集权限不允许，权限每次实时校验，非缺陷。
运行一段时间后出现认证错误：访问令牌（短期，约 1 小时）过期且自动刷新失败，可能是配对被撤销，需重新连接。
添加服务器后工具未出现：新服务器仅在下一会话挂载，重启智能体或开启新会话。
用户使用开源版 FiftyOne：该功能仅限 Voxel51，应改用本地 fiftyone-mcp 服务器。