Connect an MCP client

Give your robotics agent access to Cerulion in one client configuration. The hosted server drives cloud instances and recording analysis. The local server drives the full Cerulion CLI in your workspace and analyzes local MCAP files.

The hosted server requires you to sign in with the Cerulion account you use at app.cerulion.com. Your client opens the OAuth sign-in flow when it connects for the first time.

Hosted: `mcp.cerulion.com`

Use the hosted server when your agent needs Cloud Studio instance and DCV control or Hindsight analysis of a public recording, a presigned recording URL, or a private library bag.

Run:

claude mcp add --transport http cerulion https://mcp.cerulion.com/mcp

Ask Claude Code:

Open https://bags.example.com/2026-09-03/run.mcap and tell me why the lidar dropped out.

Open Customize → Connectors, select +, choose Add custom connector, and enter:

https://mcp.cerulion.com/mcp

Complete the OAuth sign-in flow when Claude asks you to connect.Ask Claude:

Check my Cerulion instance status, then explain whether the lidar dropout appears in https://bags.example.com/2026-09-03/run.mcap.

Add this entry to ~/.codex/config.toml:

[mcp_servers.cerulion]
url = "https://mcp.cerulion.com/mcp"

Ask Codex:

Open https://bags.example.com/2026-09-03/run.mcap, list the recorded topics, and identify the first timestamp where the lidar rate changes.

Add this server to .cursor/mcp.json:

{
  "mcpServers": {
    "cerulion": {
      "url": "https://mcp.cerulion.com/mcp"
    }
  }
}

Ask Cursor:

Analyze https://bags.example.com/2026-09-03/run.mcap and tell me whether the detector stopped receiving camera frames before the lidar dropout.

Add this server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cerulion": {
      "serverUrl": "https://mcp.cerulion.com/mcp"
    }
  }
}

Ask Cascade:

Open https://bags.example.com/2026-09-03/run.mcap and summarize the topics that were active during the safety-controller event.

Add this server to .vscode/mcp.json:

{
  "servers": {
    "cerulion": {
      "type": "http",
      "url": "https://mcp.cerulion.com/mcp"
    }
  }
}

Ask the VS Code agent:

Inspect https://bags.example.com/2026-09-03/run.mcap and explain why the camera-to-detector pipeline stopped producing detections.

Hosted Hindsight tools do not remember a recording between calls. Pass source="https://..." on every Hindsight call. A signed-in private library bag can use its bag id instead.

Local: `cerulion_mcp` over stdio

Use the local server when your agent needs workspace, node, graph, topic, schema, bag, replay, robot, or job tools. It also exposes the Hindsight tools for local MCAP files. Install the server from the cerulion-mcp workspace:

cargo install --path cerulion_mcp

Point Claude Code at the workspace you want the agent to operate on:

claude mcp add --transport stdio cerulion -- cerulion_mcp --workspace /workspaces/perception

Ask Claude Code:

Run graphs/perception.yaml for 10 seconds and show the camera and lidar topic rates.

Add this server to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "cerulion": {
      "command": "cerulion_mcp",
      "args": ["--workspace", "/workspaces/perception"]
    }
  }
}

Ask Claude:

Open the local recordings/run.mcap and list the topics that contain sensor_msgs/Image messages.

Add this entry to ~/.codex/config.toml:

[mcp_servers.cerulion]
command = "cerulion_mcp"
args = ["--workspace", "/workspaces/perception"]

Ask Codex:

Validate graphs/perception.yaml, then show the graph execution levels and any wiring diagnostics.

Add this server to .cursor/mcp.json:

{
  "mcpServers": {
    "cerulion": {
      "command": "cerulion_mcp",
      "args": ["--workspace", "${workspaceFolder}"]
    }
  }
}

Ask Cursor:

Run the perception graph for 10 seconds and compare the camera and detector topic rates.

Add this server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cerulion": {
      "command": "cerulion_mcp",
      "args": ["--workspace", "/workspaces/perception"]
    }
  }
}

Ask Cascade:

Open recordings/run.mcap, sample the lidar messages around the first detector warning, and summarize what happened.

Add this server to .vscode/mcp.json:

{
  "servers": {
    "cerulion": {
      "type": "stdio",
      "command": "cerulion_mcp",
      "args": ["--workspace", "${workspaceFolder}"]
    }
  }
}

Ask the VS Code agent:

Run graphs/perception.yaml for 10 seconds and show the topic rates for the camera, detector, and safety controller.

The local server finds cerulion on PATH. Use --bin /path/to/cerulion when the CLI is elsewhere, or set CERULION_MCP_BIN to that path. Use --source recordings/run.mcap to preselect a local recording, or set HINDSIGHT_BAG_DIR for local recording discovery.

What the agent can do

Hosted tools

Tool family	Tools	Use it for
Cloud identity and instances	`cloud_whoami`, `cloud_instance_status`, `cloud_instance_start`, `cloud_instance_stop`, `cloud_instance_reboot`	Check identity and control a Cloud Studio instance.
DCV access	`cloud_instance_connect`, `cloud_dcv_progress`, `cloud_dcv_advance`, `cloud_dcv_reset`	Connect to a running instance and move through its DCV steps.
Hindsight recordings	`open_bag`, `get_debrief`, `query_index`, `sample_messages`, `list_topics`	Brief, query, and inspect a recording.

cloud_instance_connect returns a short-lived DCV authToken, not a durable API credential.

Local tool families

Tool family	Tools
Workspace and nodes	`workspace_create`, `workspace_info`, `workspace_init`, `node_build`, `node_create`, `node_delete`, `node_info`, `node_list`, `node_modify`, `node_run`, `node_stage`
Graphs	`graph_create`, `graph_levels`, `graph_list`, `graph_partition`, `graph_profile`, `graph_run`, `graph_validate`
Topics	`topic_echo`, `topic_hz`, `topic_info`, `topic_list`, `topic_watch`
Schemas	`schema_create`, `schema_delete`, `schema_info`, `schema_list`
Bags and replay	`bag_info`, `bag_migrate`, `bag_play`, `bag_record`, `resim_compare`, `resim_get_report`, `resim_list_runs`, `resim_run`
Robots and visualization	`flashback_capture`, `viz_attach`, `robot_connect`, `robot_devices_list`, `robot_devices_revoke`, `robot_login`, `robot_pair`
Managed jobs and system	`job_list`, `job_logs`, `job_status`, `job_stop`, `system_clean`, `system_cli`, `system_help`
Hindsight recordings	`open_bag`, `get_debrief`, `query_index`, `sample_messages`, `list_topics`

Local jobs are scoped to the workspace that started them. Use that same workspace when you inspect, list, read, or stop a job.

Gotchas

Hosted Hindsight calls require a source on every call. The hosted server has no filesystem access to your local paths.
The local server needs cerulion on PATH, or an explicit --bin path.
OAuth sign-in appears on first hosted use.
cloud_instance_connect returns a short-lived DCV token. Treat it as session access, not a reusable credential.

Get started

Concepts

Guides

Reference

Hosted: `mcp.cerulion.com`

Local: `cerulion_mcp` over stdio

What the agent can do

Hosted tools

Local tool families

Gotchas

​Hosted: mcp.cerulion.com

​Local: cerulion_mcp over stdio

​What the agent can do

​Hosted tools

​Local tool families

​Gotchas

Hosted: `mcp.cerulion.com`

Local: `cerulion_mcp` over stdio

What the agent can do

Hosted tools

Local tool families

Gotchas