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:- The agent sends a tool discovery request and receives a list of all available Cyberwave tools with their schemas
- Based on your natural language instruction, the agent decides which tools to call and in what order
- Each tool call is a JSON-RPC 2.0 request sent to the MCP endpoint
- The MCP server translates the tool call into the corresponding Cyberwave REST API operation
- 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 exampleenvironment_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
Usecw_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 withcw_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_slugis omitted, the server uses the last twin from session context set by a previouscw_get_twinor any action tool call. If no twin has been used yet, the tool returns anAMBIGUOUS_TARGETerror prompting the agent to resolve the twin first. - Environments: If
environment_slugis omitted, it falls back to session context or theCYBERWAVE_ENVIRONMENT_IDenv var. Some tools (likecw_list_environment_entitiesandcw_render_environment_preview) additionally auto-resolve when only one environment is visible to the user. - Workspaces: If
workspace_slugis omitted, it falls back to session context orCYBERWAVE_WORKSPACE_ID. Tools that require a workspace auto-resolve when only one workspace is visible.
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:
- Inspect the twin schema and current joint states
- Plan with
cw_plan_control_action(route_id="joint-targets") before dispatching - Keep joint deltas small and verify each step
- Execute only after explicit confirmation
Deployment Modes
- Hosted (Recommended)
- Self-Hosted (Enterprise)
Cyberwave runs the MCP server for you. No infrastructure to manage.Alternatively:
- Endpoint:
https://mcp.cyberwave.com/mcp - Transport: Streamable HTTP
- Auth: Pass your API key with every request
X-Cyberwave-Api-Key: <CYBERWAVE_API_KEY>Generate your API key from your profile page.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
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.
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_slugis 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_taskslists tasks, returns one task’s source manifest, scene entities, orchestration hints and training options, or reads one exact source file.cw_author_rl_taskselects 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_policyhandles the trained checkpoint lifecycle: inspect, prepare/complete a signed.pt,.pth, or.zipupload, 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_labreads shared-lab availability and the caller’s current reservation, or previews/applies access requests and session release.
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
Usecw_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.