Skip to main content

Overview

The Cyberwave MCP Server exposes Cyberwave platform operations as tools that MCP-compatible clients can discover and call. Agents can inspect environments, create digital twins, position robots, capture camera frames, preview or trigger workflows, and verify results with rendered environment previews.

What is MCP?

The Model Context Protocol (MCP) is an open standard that defines how AI models discover and invoke external tools. It works like a universal adapter, any MCP-compatible AI client can connect to any MCP server and immediately know what operations are available, what parameters they accept, and what they return. When you connect the Cyberwave MCP server to an AI agent:
  1. The agent sends a tool discovery request and receives a list of all available Cyberwave tools with their schemas
  2. Based on your natural language instruction, the agent decides which tools to call and in what order
  3. Each tool call is a JSON-RPC 2.0 request sent to the MCP endpoint
  4. The MCP server translates the tool call into the corresponding Cyberwave REST API operation
  5. Results are returned to the agent, which can reason about them and decide what to do next

Slug-first entity references

MCP tool schemas advertise canonical slugs for durable Cyberwave resources — for example environment_slug, twin_slug, workflow_slug, and asset_slug — instead of opaque UUIDs. Carry the full slug returned by a list, read, or create tool into later calls rather than resolving it back to a UUID. This is not a UUID deprecation: UUID values are still accepted in every slug-first field, and legacy *_uuid argument names remain accepted as unadvertised compatibility aliases. Execution-local records without canonical slugs — workflow runs, teaching requests, checkpoints, attachments, workloads, and generation jobs — continue to use UUID-named arguments.

Available Tools

The MCP server exposes environment, catalog, workflow, AI model, dataset, control-planning, and scene-editing tools.

Discovery

Inspect

Vision

Twin Actions

Use cw_list_control_surfaces and cw_plan_control_action for twin control; for an exact target (a joint value, a waypoint, a stop) pass the discovered route_id with its inputs. Environment assistant handoff should plan only and let the Cyberwave UI/API confirmation path dispatch supported actions. To move or rotate a twin in the scene, use a cw_edit_environment update operation ({op: "update", kind: "twin", twin_slug, position, rotation}). Environment edits apply directly; ask before destructive deletes.

Environment & Area Management

Procedural Primitives

Discover procedural primitive templates with cw_search_catalog. Results include canonical slugs, template_key, template_version, parameter schemas/defaults, examples, and scene_edit_operation_hint values to copy into cw_edit_environment. Created instances persist in environment settings and include compiled bounding/collision summaries plus validation warnings.

Workflows

cw_list_node_schemas is an optional discovery aid; the workflow assistant already knows the full node catalog. Use it to confirm exact (node_type, node_subtype) identifiers, then pass them to cw_create_workflow_from_prompt via node_hints to bias the composed graph. Hints support a single fork to multiple alert/notify effects; they are advisory and unresolved hints come back as dropped_node_hints.

ML Models

Datasets


Safety Pattern

Environment object mutation tools rely on the calling agent/client for confirmation policy. Use read/list tools first, ask before destructive deletes, then call the delete tool once with normal target arguments after confirmation. Recommended sequence for environment edits:
1

Inspect

Call cw_list_environments and cw_list_environment_entities to understand the current state.
2

Confirm Deletes

For destructive deletes, resolve the target and ask the user to confirm before calling the delete tool.
3

Verify

Call cw_render_environment_preview to render a PNG snapshot. Multimodal agents can visually confirm the layout matches expectations.

Safety

Robot actions go through the same plan and dispatch path as the Cyberwave app: joint limits, scene bounds and the Live confirmation are enforced by the platform, and robot drivers bound how far a joint moves per step.

Session Context

The MCP server maintains session context to reduce verbosity. When you interact with a workspace, environment, or twin, the server remembers your last selection.
  • Twins: If twin_slug is omitted, the server uses the last twin from session context set by a previous cw_get_twin or any action tool call. If no twin has been used yet, the tool returns an AMBIGUOUS_TARGET error prompting the agent to resolve the twin first.
  • Environments: If environment_slug is omitted, it falls back to session context or the CYBERWAVE_ENVIRONMENT_ID env var. Some tools (like cw_list_environment_entities and cw_render_environment_preview) additionally auto-resolve when only one environment is visible to the user.
  • Workspaces: If workspace_slug is omitted, it falls back to session context or CYBERWAVE_WORKSPACE_ID. Tools that require a workspace auto-resolve when only one workspace is visible.
This means agents can say “capture a frame” without specifying UUIDs after they’ve already inspected a twin with cw_get_twin.

Resources

MCP resources provide read-only data URIs that agents can fetch directly without calling tools. Canonical slugs contain /, which cannot span a URI-template slot; percent-encode the slug when expanding one of these URIs (for example acme%2Fenvs%2Ffactory). A UUID also works in the same slot. Resources are useful when agents need to read structured data without triggering tool calls, for example, fetching environment awareness before deciding which twins or workflows are relevant. Visual previews remain exposed through cw_render_environment_preview so clients opt into the larger Base64 PNG payload.

Prompts

The MCP server ships with reusable prompt templates that guide agents toward safe, structured behavior. Agents can request a prompt before executing a task. For example, safe_manipulation instructs the agent to:
  1. Inspect the twin schema and current joint states
  2. Plan with cw_plan_control_action (route_id="joint-targets") before dispatching
  3. Keep joint deltas small and verify each step
  4. Execute only after explicit confirmation

Deployment Modes


Client Setup

Setup for Claude Code, Codex, Cursor, VS Code, Gemini CLI and other clients is in Connect your AI tool. It also covers installing the Cyberwave skill and verifying the connection.

Programmatic Agent Integration

Use the MCP server to build autonomous AI agents that manage Cyberwave infrastructure from your backend code.

Claude API

Claude discovers the available Cyberwave tools, plans the sequence of operations (create environment, add twin, set position), executes them through the MCP server, and can verify the result visually with cw_render_environment_preview.

OpenAI Agents SDK


Tool Reference

Vision Tools

Frame data is returned as Base64-encoded JPEG. Multimodal models can inspect it directly. When mock=true, a placeholder frame is returned for testing.

Environment & Twin Creation

cw_create_urdf_asset_from_zip carries the archive base64-encoded inside the request, so on the hosted server it is capped at 2 MiB — the streamable-HTTP transport rejects bodies over 4 MiB before the server sees them, and past roughly 3 MiB it does so as a plain-text 413 the tool never gets to improve on. A self-hosted server caps it at half of FASTMCP_MAX_REQUEST_BODY_SIZE over HTTP, and not at all over stdio. Most vendor URDFs ship meshes and exceed that. For those, call cw_begin_urdf_asset_upload, PUT the ZIP to the returned upload.upload_url with the returned upload.headers (the signature is bound to Content-Type: application/zip), then call cw_complete_urdf_asset_upload with the urdf_project_uuid and storage_key it handed back. The asset stays empty until that last call runs. To replace the package on an asset that already exists, use cw_begin_urdf_package_replacement with the asset in place of cw_begin_urdf_asset_upload, then the same PUT and cw_complete_urdf_asset_upload. It reuses the asset’s existing URDF project, so the registry id, capabilities and any twins built on the asset survive the replacement, and the current package stays live until processing completes. After the asset exists, immediately call cw_set_schema with path="/extensions/cyberwave/capabilities" to define capabilities for the newly created asset. Use capability semantics from Work with digital twins.

Aiming sensors

cw_aim_sensor(asset_slug, sensor, facing) points one named sensor forward, rear, or down, and derives the mount quaternion from the sensor’s own declared type rather than taking one from you. Imaging sensors (camera, rgb, rgbd, depth, rgb_camera, depth_camera) are aimed in their optical frame, looking down local -Z with +Y image-up; ranged sensors (lidar*, radar, rangefinder, rf_scanner, uwb_radar) are aimed in REP-103, with the beam down local +X. That difference is why the rpy="0 0 0" most vendor URDFs ship for their sensor mounts aims a lidar correctly forward while leaving every camera pointing at the floor. A sensor whose type has no aimable frame — imu, gps, audio, map — is refused rather than aimed at a guess. The tool previews by default; pass execute=true to write. cw_update_asset_actuator(asset_slug, actuator, patch) merges fields into one actuator, addressed by name. Omitted fields are left alone and a null value removes its key; name and id are refused, since renaming would move the entry being addressed. It too previews by default.

Liveries

cw_set_asset_livery(asset_slug, visual_materials) replaces an asset’s livery, the part colours the 3D viewer and the catalog thumbnail paint over its meshes. Each assignment matches visual links by link, linkPattern (a case-insensitive regex search), mesh or meshPattern, and carries a material (color as #rrggbb, metalness and roughness in [0, 1]) or the name of a preset. Where rules overlap, an exact link or mesh name beats a pattern, then the higher priority wins.
The result lists the links each rule colours, the rules that colour nothing, and the links no rule covers, which keep their own colours unless the livery has a default. A livery the renderers would skip — an unknown key, a colour that isn’t #rrggbb, a regex that doesn’t compile — is refused. Omit visual_materials to read the current livery with the same report. The tool previews by default; with execute=true it writes, and the catalog thumbnail is re-rendered. A livery can’t be removed; to correct one, write the corrected livery.

Area Tools

Area images can be attached via a direct image_url (recommended for large images) or inline as image_base64 bytes with image_mime_type. Images are stored in environment settings.

Workflow Tools

Dataset Tools

cw_download_dataset mirrors the REST endpoint: returns { status: "ready", signed_url, expires_at } on HTTP 200, or { status: "queued" | "processing", poll_url } on HTTP 202 when conversion is running. cw_wait_until_ready polls GET /datasets/{uuid} until processing_status is completed or failed. Use it after cw_list_datasets returns a dataset with status: pending following a HuggingFace import.

Environment Preview

cw_render_environment_preview(environment_slug?) renders a static PNG snapshot of the environment.
  • Calls the same backend endpoint as the web app: POST /api/v1/environments/{uuid}/preview
  • Returns attachment metadata (type=environment_preview) and a Base64 PNG payload that multimodal models can inspect directly
  • If environment_slug is omitted and only one environment is visible, it resolves automatically

RL task authoring

The MCP keeps platform-managed RL authoring and deployment behind three compact tools:
  • cw_inspect_rl_tasks lists tasks, returns one task’s source manifest, scene entities, orchestration hints and training options, or reads one exact source file.
  • cw_author_rl_task selects an authoring operation: create/update, task-local source-file upsert, scene-entity replacement, strict Python scene-spec validation/application, or generated scene-config regeneration.
  • cw_deploy_rl_policy handles the trained checkpoint lifecycle: inspect, prepare/complete a signed .pt, .pth, or .zip upload, register an uploaded attachment or HTTPS weights URL, publish a controller, and assign it to a twin with explicit replacement protection. It also previews and applies exact controller start/stop operations.
  • cw_manage_remote_lab reads shared-lab availability and the caller’s current reservation, or previews/applies access requests and session release.
Authoring previews by default. Reward, reset and termination code is uploaded as task-local source files. Applying an authoring change never starts training; inspect the result, then use cw_request_skill_teaching to prepare the existing human-confirmed training flow. Checkpoint bytes do not travel inside MCP JSON. Upload them directly with HTTP PUT to the signed URL returned by prepare_upload, then pass its handle to complete_upload. Once the published controller is assigned, call cw_start_simulation(auto_run_controllers=true) to start the simulated plant and its assigned controllers together. For physical remote-lab execution, first obtain an active reservation for the target environment with cw_manage_remote_lab; then preview and apply cw_deploy_rl_policy(operation="start_controller", mode="live") with the exact twin/controller UUIDs and confirm_live=true. Stopping or ending the session is explicit, and session release stops active controllers before handing the lab to the next user.

References

MCP Specification

Protocol and transport specification

MCP Inspector

Test and debug MCP servers

Local custom-reward training

Use cw_export_mujoco_scene with an environment UUID to obtain a MuJoCo ZIP including scene assets. Set wait_seconds=30 for bounded polling; repeat when data.status is pending. Download data.url only when data.ready is true, extract the whole archive, and load mujoco_scene.xml in MuJoCo to author and train your reward locally. Failures return status=error and details. Export requires environment read access and never starts training or robot motion. cw_request_skill_teaching remains a proposal requiring confirmation in Cyberwave. A successful export is not evidence of a trained policy’s success.