> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Let AI agents manage your robotics infrastructure through the Model Context Protocol

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](https://modelcontextprotocol.io/) | | **Transports** | `stdio` (local/self-hosted default), Streamable HTTP (hosted) | | **Hosted endpoint** | `https://mcp.cyberwave.com/mcp` | | **Authentication** | `Authorization: Bearer ` | *** ## 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 ```mermaid theme={null} flowchart TB A["You (natural language)"] --> B["AI Agent\nClaude, GPT, Gemini, Cursor, etc."] B -->|JSON-RPC 2.0 tool calls| C[Cyberwave MCP Server] C -->|REST API| D[Cyberwave Cloud Backend] D -->|MQTT| E["Edge Core → Robot Hardware"] ``` *** ## 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 template-backed workflow from a prompt via the Workflow Agent | | `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 | ### 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:** Call `cw_list_environments` and `cw_list_twins` to understand the current state. For destructive deletes, resolve the target and ask the user to confirm before calling the delete tool. 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: 1. Inspect the twin schema and current joint states 2. Call `cw_set_joint` with `execute=false` first 3. Keep joint deltas small and verify each step 4. Execute only after explicit confirmation *** ## Deployment Modes 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 ``` Alternatively: `X-Cyberwave-Api-Key: ` Generate your API key from your [profile page](https://cyberwave.com/profile). Run your own MCP server for full control over networking, auth policies, and rate limiting. ```bash theme={null} 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: ```bash theme={null} CYBERWAVE_MCP_TRANSPORT=streamable-http cyberwave-mcp-server ``` **Authentication options:** | Method | Configuration | | -------------------------------- | ----------------------------------------------------------------------- | | Environment variable (preferred) | `CYBERWAVE_API_KEY=` or `CYBERWAVE_TOKEN=` | | Credentials file | `~/.cyberwave/credentials.json` or `CYBERWAVE_CREDENTIALS_FILE=/path` | | Per-request passthrough | Client sends `Authorization: Bearer ` and the server forwards it | To enforce per-request authentication in HTTP mode: ```bash theme={null} 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 `` with your key from the [profile page](https://cyberwave.com/profile). Edit your Cursor `mcp.json` configuration file: ```json theme={null} { "mcpServers": { "cyberwave": { "url": "https://mcp.cyberwave.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Add to your VS Code `settings.json`: ```json theme={null} { "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. ```bash theme={null} claude mcp add cyberwave -t http https://mcp.cyberwave.com/mcp \ -H "Authorization: Bearer " ``` ```bash theme={null} gemini mcp add -t http cyberwave https://mcp.cyberwave.com/mcp \ --header "Authorization: Bearer " ``` Edit `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.cyberwave] command = "npx" args = ["-y", "mcp-remote@latest", "https://mcp.cyberwave.com/mcp", "--header", "Authorization: Bearer "] ``` *** ## Programmatic Agent Integration Use the MCP server to build autonomous AI agents that manage Cyberwave infrastructure from your backend code. ### Claude API ```python theme={null} 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 ```python theme={null} 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_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 *** ## References Protocol and transport specification Test and debug MCP servers