Avala

@avala-ai/mcp-server

面向 Avala API 的 Model Context Protocol（MCP）服务。它允许 Claude 和 Codex 等 Agent 通过与平台相同的租户安全 API 管理 Avala Physical AI 数据循环。

连接到 Avala 托管的 MCP 服务

在支持 OAuth 的 MCP 客户端中，将 https://mcp.avala.ai/mcp 用作远程 Streamable HTTP 服务。按提示使用 Avala 账户登录。访问需要相应的 Avala 组织权限和 MCP 授权；列入注册表并不会授予访问权限。工作人员工具需要单独的工作人员访问权限。如果登录成功，但缺少所需工具，请联系 Avala 管理员。

对于 VS Code，将以下内容添加到 .vscode/mcp.json，启动服务并完成登录：

{
  "servers": {
    "avala": {
      "type": "http",
      "url": "https://mcp.avala.ai/mcp"
    }
  }
}

先执行读取操作，例如列出账户可用的项目。工具是否可用取决于凭据权限范围和已部署的服务版本。初始注册表列表描述的是读取功能；它并不保证可以创建提案、审批或执行操作。切勿将凭据提交到客户端配置文件。有关其他客户端和 API 密钥配置，请参阅设置指南。

托管列表的元数据位于 server.json。其版本独立于 npm 包和已部署映像，单独跟踪注册表元数据。

安装

npm install -g @avala-ai/mcp-server

需要 Node.js 20+。

第一方运营技能

源码树包含 avala-physical-ai-operations， 并会将其完整目录打包到 MCP npm 包中的 skills/ 下。 它指导员工执行范围明确的监控、精确目标检查、经独立审批的调度提案，以及分开进行的执行和当前状态验证。 它不是面向客户的 QC 审批技能，也不会授予员工访问权限或作用域。

**发布可用性：**这是新增的软件包内容，旧版 0.7.4 npm 包中不包含此内容。请使用包含 skills/ 的经审核版本，或同时测试本地构建的 SDK 和 MCP 压缩包。不要根据源码检出推断内容已发布，也不要假设托管 MCP 运行的是相同版本。

将此 MCP 包安装到本地 npm 项目后，请显式将整个技能目录复制到 Agent 的技能位置。对于仓库本地的 Codex 技能，请在项目根目录运行：

test -f node_modules/@avala-ai/mcp-server/skills/avala-physical-ai-operations/SKILL.md &&
test ! -e .agents/skills/avala-physical-ai-operations &&
test ! -L .agents/skills/avala-physical-ai-operations &&
mkdir -p .agents/skills &&
cp -R node_modules/@avala-ai/mcp-server/skills/avala-physical-ai-operations .agents/skills/

存在性检查可防止重新安装时覆盖自定义技能。 替换现有副本前，请先检查并备份。请保留 references/ 和 agents/，而不仅仅是 SKILL.md。npm 安装本身不会安装 Agent 技能，也不会更改客户端配置。其他支持技能的客户端也可以在其文档指定的技能位置使用同一完整目录。

请按上述说明单独连接托管 MCP。可从以下提示词开始： “使用 $avala-physical-ai-operations 检查此确切批次的当前调度状态；报告证据缺口并提出后续步骤，但不要更改状态。” 先检查实时工具元数据：工具或作用域不可用，表示部署或访问权限存在缺口。安装技能并不代表托管服务已就绪、已获得人工审批、成功完成分配，也不代表原有客户 QC 验收流程已完成。

对于贡献者，skills/ 是规范源，并会随 SDK 镜像一起提供。两个仓库都会运行目录测试；monorepo 测试还会检查本地发现副本。bun run test:package 会构建两个软件包，在工作区外安装其实际 npm 压缩包，将完整技能复制到临时 Agent 目录，并检查内容以及是否拒绝覆盖。 它不会发布软件包，也不会调用 Avala API。

要从源码检出中检查已发布的稳定版本，请在此软件包目录运行 bun run test:release X.Y.Z，将 X.Y.Z 替换为确切的经审核版本。标签、范围、预发布版本和省略的版本都会被拒绝；该命令不会选择 latest、升级版本或发布软件包。 它会从公共 npm 注册表下载该 SDK/MCP 组合，将 MCP 压缩包安装到隔离的使用方环境中（npm 因而必须解析其实际 SDK 依赖），然后检查匹配的软件包/协议版本、完整技能和默认读取目录。注册表中的技能字节会与下载的构件进行比对，而不是与可能更新的检出文件比对。输出会记录版本、构件完整性和实际 Node 版本。npm 生命周期脚本会被禁用，不会继承凭据，并且只会删除本命令创建的临时文件。

退出码非零表示发布检查失败，包括版本缺失、依赖损坏、技能缺失或注册表不可用。特别是，旧版 0.7.4 构件不得通过此运营发布检查。安装成功并发现目录，并不代表托管服务已获得授权、来源证明已验证、API 行为正常，或真实运营/客户 QC 验收已通过。

设置

设置 API 密钥：

export AVALA_API_KEY="avk_your_api_key"

本地 stdio MCP 仅开放读取操作，除非你显式启用其旧版变更目录：

export AVALA_MCP_ENABLE_MUTATIONS=true

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "avk_your_api_key"
      }
    }
  }
}

Claude Code

claude mcp add avala -- npx -y @avala-ai/mcp-server

直接使用

avala-mcp-server

托管模式（Streamable HTTP）

该软件包还提供一个无状态的 Streamable HTTP 入口，供 Avala 的托管部署使用：

node dist/http.js

• POST /mcp — MCP 端点。每个请求都必须携带以下凭据之一：X-Avala-Api-Key: <key>、以 Authorization: Bearer 形式传入的 40 位十六进制 Avala 密钥，或针对确切 MCP 资源签发的 Auth0 OAuth 令牌。此边界会验证 OAuth 主体令牌，并通过 RFC 8693 进行交换；只有交换后面向 API 的令牌会到达 Avala 的 REST API。
• GET /.well-known/oauth-protected-resource/mcp — 公开的 RFC 9728 受保护资源元数据。身份验证失败时，会通过 WWW-Authenticate 将客户端指向此处，使支持 OAuth 的客户端能够自动发现 Auth0。
• GET / — 公开的端点／发现摘要。
• GET /healthz — 无需身份验证的存活探测。
• 双协议：当前客户端使用无状态的 2026-07-28 请求封装和 Mcp-Method／Mcp-Name 路由标头。同一个工厂也保留 SDK 的无状态 2025 兼容路径，供现有客户端使用。
• 基于提案的派发：使用 list_workforce_assignment_candidates（workforce.write 或 operations.proposal.read），然后依次使用 create_operation_proposal、evaluate_operation_proposal、request_operation_approval、get_operation_proposal、execute_approved_operation、verify_operation 和 list_operation_events。每个生命周期工具都声明其确切的 operations.* 作用域。独立审批只能通过返回的、同源 Django 管理后台 approval.reviewPath 进行；MCP 不能审批，请求人也不能自行审批。任何具有五种提案作用域之一的凭据，其写入操作都仅限提案；即使凭据同时具有旧版写入作用域，也不例外。直接分配／取消工具已移除。执行操作会将任务加入后端队列，但不能证明操作成功；请保留 UID／版本并核验所有当前观测结果。历史上的 verified 可能与当前的 changed 并存，生产活动仍未测量。由于无法观测进度，reverse_operation 只会记录一个状态为 BLOCKED 的子操作。
• 优先读取，并采用精确的旧版操作允许列表：托管 MCP 会忽略 AVALA_MCP_ENABLE_MUTATIONS。经过审核的写入操作为 change_workforce_group_membership、change_workforce_batch_allocation、create_workforce_batch、set_workforce_batch_priority、set_workforce_batch_status、set_workforce_sequence_status；这些操作仅对具有员工特权、带有 workforce.write 且不带任何提案作用域的凭据可见。每项操作都要求 MCP 询问确认、将加密确认状态绑定到确切的工具、参数、凭据、过期时间和幂等键、确切的预期状态，以及提供方侧的 MCP 审计来源信息。每个成功响应都包含不可变的 operationEventUid；请保留此值，并在将操作效果报告为已核验之前调用 get_workforce_operation_event。当回执 UID 未知时，list_workforce_operation_events 会在限定的历史窗口内进行搜索，并明确说明每个账本的存储覆盖范围。两种回执读取操作都只返回不透明目标、固定的前后效果、来源信息是否存在的布尔值，以及明确的 complete、partial 或 unavailable 核验状态；绝不返回操作人身份、原因／客户端文本、原始变更、姓名、URL、负载、薪酬、排名或综合评分。批次创建仅接受受限于特定序列的有界单元计划，默认采用明确分配的人员配置，且始终从不可用状态开始；服务器会推导协作者路由，并拒绝任意 URL 或配置。序列检查仅返回不透明 ID、工作流状态、观测令牌和获授权的后续边；绝不返回序列内容或工作流定义。当前派发健康状态只报告当前已释放、可领取的状态，并附带本次服务器观测的确切回执；若回执不可用，实时快照仍可使用，但不能声称该快照已持久记录。历史派发观测会在限定窗口内展示已记录的状态，但不会将稀疏且由读取触发的样本冒充为连续遥测数据；缺少记录不能证明状态健康或未变，当前上下文也不等于历史上下文。历史派发结果会分别报告数据库首次观测到的释放时间、首次记录的匿名服务器生成队列可见时间，以及释放后最早记录的领取时间，并明确说明释放和队列存储的缺口。队列证据既不能证明客户端已收到，也不能证明这是最早可能的可见时间；绝不会根据当前状态推断历史阻塞原因。精确旅程培训队列读取会将当前存储的注册／完成状态和最新持久化的已完成步骤证据，与当前符合条件的生产结果状态进行关联。学习注册、进度和练习数据仍以 learning.avala.ai（Vercel/Supabase）为准；Django 仅提供与生产证据的有限关联。对于返回的、未观测到当前符合条件输出的成员，同一读取操作还会提供每项练习的当前课程结果计数和正向负载失败诊断。失败但无通过记录，只表示尚无定论的已记录证据；它不代表因果性流失、实际停滞、技能、意图或排名；没有负载失败记录也不能证明成功。在作出任何全局练习声明之前，请先汇总所有未变化游标页面中的稳定练习步骤 UID。读取结果会明确排除已删除／覆盖的注册和练习行历史、历史付款、序列结果、提示词、答案、分数、原始负载以及浏览器／构建标签。除非提供方标明已完成核对，否则不会将页面摘要表述为全局摘要。精确协作者旅程读取仅针对调用方提供的协作者 UID，关联账户就绪状态、学习、任务访问权限和非练习类生产数据；该读取会显示安全标签和有证据支持的诊断，同时排除联系方式、提供方身份、KYC、薪酬和客户负载，并传播关联提供方的失败，而不会伪造零值。单元检查绝不暴露协作者身份；具有写入作用域的组发现会返回稳定组 UID、内部标签和汇总成员就绪状态，不返回成员行或实时容量声明。单独的成员名册仅读取不透明协作者 UID、安全的名字／回退标签，以及 active、approved 和 active-work 布尔值；绝不返回联系／资料数据、权限、薪酬、绩效、客户负载或工作详情。精确批次活动监控会返回不透明协作者 ID、当前分配状态和有界原始活动；绝不暴露身份字段、工作详情、排名、费率或综合绩效评分。change_workforce_group_membership 要求提供 preview_workforce_group_membership_impact 返回的每个确切字段、两项明确的全局／能力确认，以及单独的人工审批；它会拒绝已知的无操作请求，以及会因目标组存在进行中工作而受阻的移除操作。全局组成员资格可能影响所列生产线路之外的工作资格和平台能力。批次分配是范围更窄的调度控制：人员名册和影响预览仅暴露不透明 ID、就绪状态、固定计数和原始的组织范围结果，而 change_workforce_batch_allocation 绝不会更改全局组资格。候选人发现绝不返回排名、综合评分、资料、客户负载或薪酬数据。
• 会话和工位监控：get_workforce_session_monitoring 和 get_workforce_station_monitoring 要求具备员工访问权限和 workforce.read。会话监控接受 endedFrom／endedBefore，用于指定最多 31 天的过去半开区间，并按 ended_at 统计结束记录；缺少历史结束时间的记录仍视为未知。其定义涵盖所有项目，每种状态最多采样 1000 条最新创建的记录；statusCountsComplete 为 false 时表示计数为下限，只有两种终止状态都完整时，区间数据才算完整。工位监控仅统计保留的 SessionTask 关联记录：恢复操作可能会删除关联，历史覆盖范围不完整，跨工位计数不可相加。工位读取最多采样 1000 条关联记录；countsComplete 为 false 时表示计数为下限，而 unknownStatusTaskLinks 会保留状态未知的采样关联记录。两者都使用有界 UID 分页（limit 为 1–10，默认 5；使用 nextCursor 时请保留筛选条件）。两者都不能证明标注已完成的吞吐量、上传／接受情况、计费、安全重新分配、Redis 队列可见性或基础设施健康状况。
• 协作者队列输出证据：get_workforce_coworker_reliability 是一项使用假名、限定于 workforce.write 作用域的员工读取操作。它会区分采样得到的无工作观测与采样得到的有工作可用但无输出观测，拒绝存储窗口不完整的情况，并明确声明不代表完整的出勤情况、计划可用性、意图或故意闲置。
• 资源句柄：读取操作会返回短时有效的不透明句柄，而非提供方签名的媒体和导出 URL。resolve_asset_handle 会使用 MCP 询问确认，验证由服务器签发、与确切句柄绑定的短时有效确认挑战，然后使用当前凭据重新获取资源。对于不支持、已拒绝、伪造或跨句柄重放的确认，不会释放 URL。
• 浏览器 Origin 验证适用于 /mcp；公开的存活和发现路由不包含凭据功能。 托管运营方必须配置 AVALA_MCP_INTERNAL_CLIENT_SECRET、AVALA_MCP_OAUTH_RESOURCE、AVALA_MCP_OAUTH_ISSUER、AVALA_MCP_OAUTH_API_AUDIENCE、AVALA_MCP_OAUTH_CLIENT_ID、AVALA_MCP_OAUTH_CLIENT_SECRET，以及以空格分隔的 AVALA_MCP_OAUTH_SCOPES。对于基于提案的员工操作，请声明 mcp.staff_access、workforce.read、operations.proposal.read、operations.proposal.create、operations.approval.request、operations.execution.request 和 operations.verification.read。Auth0 仍要求分配管理员角色，Django 仍要求 is_staff=True；声明作用域绝不会将这些权限授予客户。省略必需的作用域会导致相应工具无法发现或返回 403 响应。workforce.read 提供有界的生产监控和旅程证据；operations.proposal.read 还允许发现分配候选对象，无需 workforce.write。

仅当部署支持需要不可变操作回执、内部群组发现、群组和批次人员配置名单、特定批次活动、影响预览，或六项经过审核的群组成员关系、批次分配、批次创建、批次优先级、批次生命周期和序列生命周期操作的独立旧版员工凭证时，才添加 workforce.write。即使提案凭证也携带 workforce.write，仍无法使用这些旧版写入操作。直接分配／取消分配工具已移除。PORT、AVALA_BASE_URL 和以逗号分隔的 ALLOWED_ORIGINS 仍为可选项。机密值应存放在部署密钥库中，绝不可放在环境模板或源代码管理中。

伪匿名队列输出比较同样需要 workforce.write；如果部署不应公开个人级运营证据，请省略该作用域。

与 stdio 模式不同，服务器不会读取 AVALA_API_KEY 环境变量——它是多租户的，每个请求使用一个凭证。

可用工具

工具类别	说明
数据集	列出并检查数据集、序列、帧、校准、摄取状态、采集活动和提交
项目	列出并检查项目
导出	列出、检查并创建标注导出
设备群组	设备管理、录制内容、事件、警报、规则
Agent	列出并检查自动化 Agent
Webhook	列出并检查 Webhook 订阅
存储	列出存储配置
质量	质量目标、每次采集的判定证据、活动验收产出率和覆盖率，以及共识评分
标注问题	列出并管理标注问题数据
组织	列出组织和成员
切片	列出并检查数据切片
资产	在确认并使用当前凭据完成访问检查后，解析不透明的媒体或导出句柄
统计	获取账户概览统计信息
工作流	组合工具：设备群组健康概览、项目质量摘要、工作区概览、标注流水线创建
员工	仅供 Avala 员工使用：SQL 沙盒代理、生产聚合监控、精确旅程培训队列证据、当前及抽样历史派发证据、发布 → 队列曝光 → 认领结果、有界生产线清单、假名化队列输出证据、不可变操作回执验证、群组/成员就绪状态、批次/单元关注项、信号支持的不透明分配候选项，以及经确认的队列控制
注意	本地 stdio 旧版写入操作（create_*、delete_*、test_storage_config、evaluate_quality、compute_consensus）需要设置 AVALA_MCP_ENABLE_MUTATIONS=true；托管 MCP 会忽略该标志。

文档

• MCP 设置指南
• TypeScript SDK 指南
• API 参考

许可证

MIT — 详见 LICENSE。

如需进行只读的应用就绪性检查，请在 monorepo 中运行 python scripts/mcp_production_readiness.py --phase proposal-readiness --json，并通过常规环境设置 AVALA_MCP_PROPOSAL_BEARER_TOKEN 和 AVALA_MCP_CANARY_OPERATION_PROPOSAL_UID。请使用具有 workforce.read 和全部五个提案作用域的员工提案凭据，并提供一份已执行的现有提案。此检查会检查全部八个生命周期工具，且只调用三个 GET 工具；它不会创建、批准、执行或撤销任何内容，也不能确定基础设施或部署是否就绪。

提案响应会保留 snapshotCanonicalJson，即提供方精确冻结的哈希输入。对其未经修改的 UTF-8 字节计算 SHA-256，结果等于 snapshotHash；不要重新序列化类型化快照来复现摘要。MCP 边界会在返回这些字节前，检查它们与有限类型化快照之间的精确对应关系。

记录的收入和账单

具有明确授予的 billing.read 的员工凭据可调用 get_billing_coworker_earnings 和 list_billing_organizations。劳动力授权不包含财务访问权限。收入会根据过去最多 31 天的半开时间窗口，按结束时间筛选完整的已记录支付周期。请保留货币和十进制字符串精度；时间单位为毫秒。这些读取操作不会计算待结算收入、核实结算情况、公开发票，也不会将成本归属到工作批次。组织状态是存储的数据，并非实时提供方检查。