MCP Server - Cyberwave Docs

Cyberwave is in Private Beta.

Request early access to get access to the Cyberwave dashboard.

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.


Protocol	JSON-RPC 2.0 over Model Context Protocol
Transports	`stdio` (local/self-hosted default), Streamable HTTP (hosted)
Hosted endpoint	`https://mcp.cyberwave.com/mcp`
Authentication	`Authorization: Bearer <CYBERWAVE_API_KEY>`

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

Available Tools

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

Discovery

Tool	Description
`cw_list_workspaces`	List available workspaces
`cw_list_projects`	List projects, optionally filtered by workspace
`cw_list_environments`	List environments, optionally filtered by project
`cw_list_twins`	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
`cw_list_areas`	List areas (zones/regions) in an environment

Inspect

Tool	Description
`cw_get_environment_context`	Get compact environment awareness: metadata, areas, twins, workflows, session hints, and preview guidance
`cw_get_twin`	Get a twin by UUID or session-resolved twin
`cw_get_joint_states`	Get current joint states for a twin
`cw_get_schema`	Get a twin’s universal schema at a JSON Pointer path
`cw_render_environment_preview`	Render a PNG snapshot of the environment (multimodal agents can visually inspect the 3D scene)

Vision

Tool	Description
`cw_capture_frame`	Capture the latest camera frame from a twin (returns Base64 JPEG)
`cw_capture_frames`	Capture multiple frames (up to 10) with configurable interval

Twin Actions

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.

Tool	Description
`cw_edit_position`	Move a twin to specific x, y, z coordinates
`cw_edit_rotation`	Rotate a twin (Euler angles or quaternion)
`cw_set_joint`	Set a single joint position (degrees or radians)
`cw_motion_pose`	Apply a named motion pose or a custom joint map
`cw_navigation_goto`	Navigate a twin to a waypoint position
`cw_navigation_stop`	Stop an active navigation command

Environment & Area Management

Tool	Description
`cw_create_environment`	Create a new environment in a workspace/project
`cw_add_twin_to_environment`	Add a twin to an environment from a catalog `registry_id`
`cw_create_urdf_asset_from_zip`	Create a new asset from a URDF ZIP package
`cw_set_asset_capabilities`	Set capabilities at `/extensions/cyberwave/capabilities` for an asset
`cw_create_area`	Create a new area/zone in an environment
`cw_resize_area`	Resize an area by setting new dimensions
`cw_set_area_image`	Attach or remove a background image on an area (via URL or Base64)

Scene Planning

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.

Procedural Primitives

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.

Workflows

Tool	Description
`cw_list_workflows`	List workflows for the current or provided environment
`cw_create_workflow_from_prompt`	Preview or draft a workflow from a prompt via the Workflow Agent; accepts optional `node_hints`
`cw_list_node_schemas`	List registered node schemas. Optional `query` is a ranked keyword search (space-separated terms, OR-matched, best-first), not a literal phrase
`cw_get_node_schema`	Get the typed parameter contract for one `(node_type, node_subtype)`
`cw_get_workflow`	Get a workflow by UUID (nodes, connections, config)
`cw_trigger_workflow`	Trigger a workflow run with optional input parameters
`cw_list_workflow_runs`	List workflow runs, optionally filtered by workflow or status
`cw_get_workflow_run`	Get a specific workflow run by UUID
`cw_cancel_workflow_run`	Cancel an active workflow run

stub: cw_list_node_schemas is an optional discovery aid; the Workflow Agent 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

Tool	Description
`cw_list_models`	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

Datasets

Tool	Description
`cw_list_datasets`	List datasets, optionally filtered by workspace
`cw_get_dataset`	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
`cw_delete_dataset`	Soft-delete a dataset by UUID

Safety Pattern

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:

Inspect

Call cw_list_environments and cw_list_twins to understand the current state.

Confirm Deletes

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

Verify

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

Safety Limits

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.

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_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.

Resources

MCP resources provide read-only data URIs that agents can fetch directly without calling tools.

URI	MIME Type	Description
`cyberwave://environment/current/context`	`application/json`	Compact context for the current environment resolved from request headers, session, defaults, or the only visible environment
`cyberwave://environments/{environment_uuid}/context`	`application/json`	Compact environment awareness context
`cyberwave://environments/{environment_uuid}/areas`	`application/json`	All areas defined in an environment
`cyberwave://environments/{environment_uuid}/twins`	`application/json`	Compact twin summaries for an environment
`cyberwave://environments/{environment_uuid}/workflows`	`application/json`	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.

Prompts

The MCP server ships with reusable prompt templates that guide agents toward safe, structured behavior.

Prompt	Description	When to use
`safe_navigation`	Plans navigation with safety checks and execute gating	Moving twins to waypoints
`safe_manipulation`	Plans joint manipulation with delta checks and preview-first flow	Setting joints or applying poses
`inspect_then_act`	General policy: always inspect context before any actions	Default policy for any task

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
Call cw_set_joint with execute=false first
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.

Endpoint: https://mcp.cyberwave.com/mcp
Transport: Streamable HTTP
Auth: Pass your API key with every request

Authorization: Bearer <CYBERWAVE_API_KEY>

Alternatively: X-Cyberwave-Api-Key: <CYBERWAVE_API_KEY>Generate your API key from your profile page.

Run your own MCP server for full control over networking, auth policies, and rate limiting.

cd cyberwave-clis/cyberwave-mcp-server
pip install -e .
cyberwave-mcp-server

By default the server runs in stdio mode (for local IDE use). To switch to HTTP for remote clients:

CYBERWAVE_MCP_TRANSPORT=streamable-http cyberwave-mcp-server

Authentication options:

Method	Configuration
Environment variable (preferred)	`CYBERWAVE_API_KEY=<token>` or `CYBERWAVE_TOKEN=<token>`
Credentials file	`~/.cyberwave/credentials.json` or `CYBERWAVE_CREDENTIALS_FILE=/path`
Per-request passthrough	Client sends `Authorization: Bearer <token>` and the server forwards it

To enforce per-request authentication in HTTP mode:

CYBERWAVE_MCP_REQUIRE_REQUEST_API_KEY=true

Client Setup

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.

Cursor
VS Code
Claude Code
Gemini CLI
Codex CLI

Edit your Cursor mcp.json configuration file:

{
  "mcpServers": {
    "cyberwave": {
      "url": "https://mcp.cyberwave.com/mcp",
      "headers": {
        "Authorization": "Bearer <CYBERWAVE_API_KEY>"
      }
    }
  }
}

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "cyberwave": {
        "url": "https://mcp.cyberwave.com/mcp",
        "headers": {
          "Authorization": "Bearer ${env:CYBERWAVE_API_KEY}"
        }
      }
    }
  }
}

Set the CYBERWAVE_API_KEY environment variable and restart VS Code, or replace ${env:CYBERWAVE_API_KEY} with your key directly.

claude mcp add cyberwave -t http https://mcp.cyberwave.com/mcp \
  -H "Authorization: Bearer <CYBERWAVE_API_KEY>"

gemini mcp add -t http cyberwave https://mcp.cyberwave.com/mcp \
  --header "Authorization: Bearer <CYBERWAVE_API_KEY>"

Edit ~/.codex/config.toml:

[mcp_servers.cyberwave]
command = "npx"
args = ["-y", "mcp-remote@latest", "https://mcp.cyberwave.com/mcp", "--header", "Authorization: Bearer <CYBERWAVE_API_KEY>"]

Programmatic Agent Integration

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

Claude API

import anthropic

client = 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.

OpenAI Agents SDK

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

mcp_server = MCPServerStreamableHttp(
    params={
        "url": "https://mcp.cyberwave.com/mcp",
        "headers": {"Authorization": "Bearer YOUR_CYBERWAVE_API_KEY"},
    },
    name="cyberwave",
)

agent = Agent(
    name="Cyberwave Agent",
    instructions="Use Cyberwave MCP tools to inspect before acting.",
    mcp_servers=[mcp_server],
)

result = Runner.run_sync(agent, "List my available workspaces.")
print(result.final_output)

Tool Reference

Vision Tools

Tool	Parameters
`cw_capture_frame`	`twin_uuid?`, `sensor_id?`, `mock?` (default `false`)
`cw_capture_frames`	`twin_uuid?`, `count` (1–10, default 1), `interval_ms` (0–5000, default 0), `sensor_id?`, `mock?`

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

Twin Action Tools

Tool	Parameters
`cw_edit_position`	`twin_uuid?`, `x?`, `y?`, `z?` (at least one required), `execute=false`
`cw_edit_rotation`	`twin_uuid?`, `yaw?`, `pitch?`, `roll?`, `quaternion?` (Euler or quaternion, not both), `execute=false`
`cw_set_joint`	`twin_uuid?`, `joint_name` (required), `position`, `degrees` (default `true`), `execute=false`
`cw_motion_pose`	`twin_uuid?`, `name?`, `joints?` (name or joints required), `scope` (`asset`/`twin`/`environment`), `environment_uuid?`, `sync`, `transition_ms?`, `hold_ms?`, `execute=false`
`cw_navigation_goto`	`twin_uuid?`, `position` (required, `[x, y, z]`), `yaw?`, `rotation?` (`[w, x, y, z]`, mutually exclusive with yaw), `environment_uuid?`, `execute=false`
`cw_navigation_stop`	`twin_uuid?`, `environment_uuid?`, `execute=false`

Environment & Twin Creation

Tool	Parameters
`cw_create_environment`	`name` (required), `workspace_uuid?`, `project_uuid?`, `description?`, `execute=false`
`cw_add_twin_to_environment`	`registry_id` (required), `environment_uuid?`
`cw_create_urdf_asset_from_zip`	`name` (required), `zip_file_base64` (required), `zip_file_name` (default `asset.zip`), `workspace_uuid?`, `description?`, `visibility` (default `private`), `main_file_path?`, `metadata?`
`cw_set_asset_capabilities`	`asset_uuid_or_registry_id` (required), `capabilities` (required object), `execute=false`

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 Tools

Tool	Parameters
`cw_list_areas`	`environment_uuid?`
`cw_create_area`	`name`, `environment_uuid?`, `area_id?`, `position?` (`[x,y,z]`), `size?` (`[x,y,z]`), `rotation?`, `image_url?`, `image_base64?`, `image_mime_type`, `keep_proportions`, `opacity`, `color`, `locked`, `visible`
`cw_resize_area`	`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.

Workflow Tools

Tool	Parameters
`cw_list_workflows`	(none)
`cw_list_node_schemas`	`query?` (ranked keyword search), `limit=100`
`cw_get_node_schema`	`node_type` (required), `node_subtype?`
`cw_get_workflow`	`workflow_uuid` (required)
`cw_trigger_workflow`	`workflow_uuid` (required), `inputs?` (dict), `execute=false`
`cw_list_workflow_runs`	`workflow_uuid?`, `status?`
`cw_get_workflow_run`	`run_uuid` (required)
`cw_cancel_workflow_run`	`run_uuid` (required), `execute=false`

Dataset Tools

Tool	Parameters
`cw_list_datasets`	`workspace_uuid?`
`cw_get_dataset`	`dataset_uuid` (required)
`cw_wait_until_ready`	`dataset_uuid` (required), `poll_interval?` (default 5 s), `timeout?` (default 1800 s)
`cw_download_dataset`	`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.

Environment Preview

cw_render_environment_preview(environment_uuid?) 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_uuid is omitted and only one environment is visible, it resolves automatically

​Overview

​What is MCP?

​Available Tools

​Discovery

​Inspect

​Vision

​Twin Actions

​Environment & Area Management

​Scene Planning

​Procedural Primitives

​Workflows

​ML Models

​Datasets

​Safety Pattern

​Safety Limits

​Session Context

​Resources

​Prompts

​Deployment Modes

​Client Setup

​Programmatic Agent Integration

​Claude API

​OpenAI Agents SDK

​Tool Reference

​Vision Tools

​Twin Action Tools

​Environment & Twin Creation

​Area Tools

​Workflow Tools

​Dataset Tools

​Environment Preview

​References

MCP Specification

MCP Inspector

Overview

What is MCP?

Available Tools

Discovery

Inspect

Vision

Twin Actions

Environment & Area Management

Scene Planning

Procedural Primitives

Workflows

ML Models

Datasets

Safety Pattern

Safety Limits

Session Context

Resources

Prompts

Deployment Modes

Client Setup

Programmatic Agent Integration

Claude API

OpenAI Agents SDK

Tool Reference

Vision Tools

Twin Action Tools

Environment & Twin Creation

Area Tools

Workflow Tools

Dataset Tools

Environment Preview

References