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.
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
List digital twins, optionally filtered by environment
cw_search_catalog
Search asset catalog and procedural primitive templates by text query
cw_plan_scene
stub: Plan a semantic scene without mutation, returning Scene DSL, catalog candidates, advisory tool steps, validation checks, and warnings
cw_list_control_surfaces
stub: List twins and available controls before planning a control intent
cw_plan_control_action
stub: Plan movement, stop, observation, or controller-policy intents without MCP execution
cw_resolve_control_route
stub: Resolve a backend route into a plan without execution
cw_dispatch_control_action
stub: Dispatch one explicit action returned by planning or route resolution
legacy execute tools
stub: cw_set_joint, cw_motion_pose, cw_navigation_goto, and cw_navigation_stop auto-dispatch only when backend route resolution returns exactly one dispatchable action
stub: Prefer cw_list_control_surfaces and cw_plan_control_action for assistant-driven twin control. Older twin action tools still expose execute for hardware/simulation safety, but Environment Assistant handoff should plan only and let the Cyberwave UI/API confirmation path dispatch supported actions. Environment object creation and transform tools apply direct edits; ask before destructive deletes.
stub: Use cw_plan_scene(prompt, environment_uuid?, scenario_type?) as an advisory planning aid before broad scene-generation prompts. It does not mutate the environment, auto-apply templates, or return executable mutation batches. The plan uses Scene DSL version 0.1: zones map to areas, structures/static objects map to template-backed procedural primitives, route points map to waypoints, and catalog assets map to catalog search/add-twin hints.
stub: Discover procedural primitive templates with cw_search_catalog. Results include canonical slugs, template_key, template_version, parameter schemas/defaults, examples, and cw_create_procedural_primitive hints. Created instances persist in environment settings and include compiled bounding/collision summaries plus validation warnings.
List ML model catalog records visible to the user; optional workspace_uuid (client-side filter: that workspace plus public rows); optional deployment ("cloud", "edge", or "hybrid")
cw_get_model
Get full details for a single model record by UUID
cw_delete_model
Delete a model catalog record — call with execute=false to preview, then execute=true to confirm
Get full dataset details including processed_datasets conversion status
cw_wait_until_ready
Poll a dataset until ingestion reaches completed or failed — use after a HuggingFace import (async)
cw_download_dataset
Request a download URL for a specific output format — triggers conversion if needed and returns signed_url when ready or status: queued when conversion is in flight
stub: 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_twins 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.
Action tools enforce safety guardrails before executing. These limits can be configured via environment variables on self-hosted deployments.
Limit
Default
Env var
Max position delta
2.0 m
CYBERWAVE_MCP_MAX_POSITION_DELTA_M
Max navigation distance
5.0 m
CYBERWAVE_MCP_MAX_NAV_DISTANCE_M
Max joint delta
0.7 rad
CYBERWAVE_MCP_MAX_JOINT_DELTA_RAD
If a tool call exceeds these limits, the server returns an error with code POSITION_DELTA_TOO_LARGE, NAV_DISTANCE_TOO_LARGE, or JOINT_DELTA_TOO_LARGE instead of executing the action.
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_uuid 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_uuid is omitted, it falls back to session context or the CYBERWAVE_ENVIRONMENT_ID env var. Some tools (like cw_list_areas and cw_render_environment_preview) additionally auto-resolve when only one environment is visible to the user.
Workspaces: If workspace_uuid 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.
Compact workflow summaries related to an environment
cyberwave://env/{environment_uuid}/areas
application/json
All areas defined in an environment
cyberwave://env/{environment_uuid}/twins
application/json
All twins in an environment
cyberwave://twin/{twin_uuid}/schema
application/json
Twin universal schema (URDF-derived structure)
cyberwave://twin/{twin_uuid}/state
application/json
Twin state plus current joint states
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.
Connect the Cyberwave MCP server to your preferred AI client. All examples use the hosted endpoint, replace <CYBERWAVE_API_KEY> with your key from the profile page.
import anthropicclient = anthropic.Anthropic()response = client.beta.messages.create( model="claude-opus-4-1", max_tokens=1024, messages=[{ "role": "user", "content": "Create an environment with an SO101 arm positioned at x=1, y=0, z=0.5" }], mcp_servers=[{ "type": "url", "name": "cyberwave", "url": "https://mcp.cyberwave.com/mcp", "authorization_token": "YOUR_CYBERWAVE_API_KEY" }], tools=[{"type": "mcp_toolset", "mcp_server_name": "cyberwave"}],)
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.
stub: After calling cw_create_urdf_asset_from_zip, immediately call cw_set_asset_capabilities to define capabilities for the newly created asset. Use capability semantics from the Digital Twins documentation (/use-cyberwave/digital-twins/overview).
area_id (required), environment_uuid?, x?, y?, z? (at least one, must be > 0)
cw_set_area_image
area_id (required), environment_uuid?, image_url?, image_base64?, image_mime_type, keep_proportions?, remove_image? (exactly one of remove/url/base64), execute=false
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.
dataset_uuid (required), format (required — e.g. parquet, lerobot3, rlds, openvla)
cw_delete_dataset
dataset_uuid (required)
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.
