Avala

@avala-ai/mcp-server

Model Context Protocol (MCP) server for the Avala API. It lets agents such as Claude and Codex manage the Avala Physical AI data loop through the same tenant-safe APIs used by the platform.

Connect to Avala's hosted MCP

Use https://mcp.avala.ai/mcp as a remote Streamable HTTP server in an OAuth-capable MCP client. Sign in with your Avala account when prompted. Access requires the corresponding Avala organization permissions and MCP grants; a registry listing does not grant access. Staff tools require separate staff access. Ask your Avala administrator if sign-in succeeds but the required tools are missing.

For VS Code, add this to .vscode/mcp.json, start the server, and complete sign-in:

{

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

Begin with a read, such as listing the projects available to your account. Tool availability follows your credential scopes and the deployed server version. The initial registry listing describes read capabilities; it does not promise proposal creation, approval, or execution. Never commit credentials to client configuration files. See the setup guide for additional clients and API-key configuration.

The hosted listing metadata lives in server.json. Its version tracks registry metadata independently of the npm package and deployed image.

Installation

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

Requires Node.js 20+.

First-party operations skill

The source tree includes avala-physical-ai-operations and packages its complete directory under skills/ in the MCP npm artifact. It guides staff through bounded monitoring, exact-target inspection, independently approved dispatch proposals, and separate execution/current-state verification. It is not a customer QC approval skill and does not grant staff access or scopes.

Release availability: this is new package content, not present in the older 0.7.4 npm artifact. Use a reviewed release that contains skills/, or test the locally built SDK and MCP tarballs together. Do not infer publication from a source checkout or assume the hosted MCP runs the same version.

After installing that MCP package into a local npm project, explicitly copy the whole skill directory into your agent's skill location. For a repository-local Codex skill, run from the project root:

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/

The existence checks stop a reinstall from overwriting a customized skill. Review and back up an existing copy before replacing it. Preserve references/ and agents/, not just SKILL.md. npm installation itself does not install an agent skill or change client configuration. Other skill-capable clients can use the same complete directory in their documented skill location.

Connect the hosted MCP separately as described above. Start with: “Use $avala-physical-ai-operations to inspect the current dispatch state for this exact batch; report evidence gaps and propose next steps without changing it.” Inspect live tool metadata first: unavailable tools or scopes are a deployment or access gap. Skill installation does not establish hosted readiness, human approval, successful assignment, or the original customer QC acceptance flow.

For contributors, skills/ is the canonical source and travels with the SDK mirror. Catalog tests run in both repositories; monorepo tests additionally check the local discovery copy. bun run test:package builds both packages, installs their actual npm tarballs outside the workspace, copies the complete skill into a disposable agent directory, and checks content and overwrite refusal. It does not publish or call the Avala API.

To check an already published stable release from a source checkout, run bun run test:release X.Y.Z from this package directory, replacing X.Y.Z with the exact reviewed version. Tags, ranges, prereleases and omitted versions are refused; the command never selects latest, bumps a version or publishes. It downloads that SDK/MCP pair from the public npm registry, installs only the MCP tarball into an isolated consumer (so npm must resolve its actual SDK edge), then checks matching package/protocol versions, the complete skill and default read catalog. Registry skill bytes are compared with that downloaded artifact, not potentially newer checkout files. The output records version, artifact integrities and actual Node version. npm lifecycle scripts are disabled, inherited credentials are excluded, and only owned temporary files are removed.

A nonzero exit is a failed release check, including a missing version, a broken dependency, missing skill or unavailable registry. In particular, the old 0.7.4 artifact must not pass this operations-release check. Successful installation and catalog discovery do not establish hosted authorization, provenance attestation, API behavior or real Operations/customer-QC acceptance.

Setup

Set your API key:

export AVALA_API_KEY="avk_your_api_key"

Local stdio MCP exposes only reads unless you explicitly enable its legacy mutation catalog:

export AVALA_MCP_ENABLE_MUTATIONS=true

Claude Desktop

Add to your 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

Direct Usage

avala-mcp-server

Hosted mode (Streamable HTTP)

The package also ships a stateless Streamable HTTP entry, used by Avala's hosted deployment:

node dist/http.js

• POST /mcp — the MCP endpoint. Every request carries either X-Avala-Api-Key: , a 40-hex Avala key as Authorization: Bearer, or an Auth0 OAuth token issued for the exact MCP resource. OAuth subject tokens are verified at this boundary and exchanged through RFC 8693; only the resulting API-audience token reaches Avala's REST API.
• GET /.well-known/oauth-protected-resource/mcp — public RFC 9728 protected-resource metadata. Authentication failures point clients here through WWW-Authenticate, enabling OAuth-capable clients to discover Auth0 automatically.
• GET / — public endpoint/discovery summary.
• GET /healthz — unauthenticated liveness probe.
• Dual protocol: current clients use the stateless 2026-07-28 request envelope and Mcp-Method / Mcp-Name routing headers. The same factory retains the SDK's stateless 2025 compatibility path for existing clients.
• Proposal-backed dispatch: use list_workforce_assignment_candidates (workforce.write OR operations.proposal.read), then create_operation_proposal, evaluate_operation_proposal, request_operation_approval, get_operation_proposal, execute_approved_operation, verify_operation, and list_operation_events. Each lifecycle tool declares its exact operations.* scope. Independent approval is available only through the returned same-origin Django admin approval.reviewPath; MCP cannot approve, and the requester cannot self-approve. Any credential with one of the five proposal scopes is proposal-only for writes, including credentials that also carry legacy write scopes. Direct assignment/cancellation tools have been removed. Execution queues a backend task and does not prove success; preserve UID/version and verify all current observations. Historical verified may coexist with current changed, and productive activity remains unmeasured. reverse_operation only records a BLOCKED child because progress observability is unavailable.
• Read-first with an exact legacy action allowlist: hosted MCP ignores AVALA_MCP_ENABLE_MUTATIONS. Its reviewed writes are change_workforce_group_membership, change_workforce_batch_allocation, create_workforce_batch, set_workforce_batch_priority, set_workforce_batch_status, set_workforce_sequence_status, visible only to a staff-privileged credential carrying workforce.write and none of the proposal scopes. Each action requires MCP elicitation, encrypted confirmation state bound to the exact tool, arguments, credential, expiry and idempotency key, exact expected state, and provider-side MCP audit provenance. Every successful response includes an immutable operationEventUid; preserve it and call get_workforce_operation_event before reporting the effect as verified. When a receipt UID is unknown, list_workforce_operation_events searches a bounded past window with explicit per-ledger storage coverage. Both receipt reads return only opaque targets, fixed before/after effects, provenance-presence booleans, and an explicit complete, partial, or unavailable verification status—never actor identity, reason/client text, raw changes, names, URLs, payloads, pay, rankings, or composite scores. Batch creation accepts only a bounded sequence-scoped unit plan, defaults to explicit allocated staffing, and always starts unavailable; the server derives coworker routes and rejects arbitrary URLs or configuration. Sequence inspection returns only opaque IDs, workflow state, observation tokens, and authorized next edges—never sequence contents or workflow definitions. Current dispatch health reports only present released-to-claimable state and includes an exact receipt for its sampled server observation; an unavailable receipt leaves the live snapshot usable but prevents claiming it was durably recorded. Historical dispatch observations expose those recorded states over bounded windows without pretending sparse, read-triggered samples are continuous telemetry; absent rows do not prove health or unchanged state, and current context is not historical context. Historical dispatch outcomes separately report first database-observed release, first recorded anonymous server-generated queue visibility, and earliest recorded post-release claim, with explicit release and queue-storage gaps. Queue evidence proves neither client receipt nor earliest possible visibility, and historical blocker attribution is never inferred from current state. The exact-journey training-cohort read joins current stored enrollment/completion and latest durable completed-step evidence to current qualifying production-result state. Learning enrollment, progress, and practice data remains authoritative at learning.avala.ai (Vercel/Supabase); Django only supplies the bounded join to production evidence. For returned members without observed current qualifying output, the same read includes per-exercise current-curriculum outcome counts and positive load-failure diagnostics. Failure without pass is unresolved recorded evidence—not causal dropoff, actual stall, skill, intent, or ranking—and absence of a load-failure row does not prove success. Aggregate stable exercise step UIDs across every unchanged cursor page before any global practice claim. The read explicitly excludes deleted/overwritten enrollment and practice-row history, historical payouts, sequence results, prompts, answers, scores, raw payloads, and browser/b