> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cerulion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP client

> Connect Claude, Codex, Cursor, Windsurf, or VS Code to Cerulion over hosted HTTP or local stdio.

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

<Warning>
  The hosted server requires you to sign in with the Cerulion account you use at
  [app.cerulion.com](https://app.cerulion.com). Your client opens the OAuth sign-in
  flow when it connects for the first time.
</Warning>

***

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

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    Run:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Claude Desktop / claude.ai" icon="message">
    Open **Customize → Connectors**, select **+**, choose **Add custom connector**,
    and enter:

    ```text theme={null}
    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`.
  </Tab>

  <Tab title="Codex" icon="terminal">
    Add this entry to `~/.codex/config.toml`:

    ```toml theme={null}
    [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.
  </Tab>

  <Tab title="Cursor" icon="cursor">
    Add this server to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Windsurf" icon="wind">
    Add this server to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code" icon="code">
    Add this server to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

***

## 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:

```bash theme={null}
cargo install --path cerulion_mcp
```

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    Point Claude Code at the workspace you want the agent to operate on:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Claude Desktop" icon="message">
    Add this server to `claude_desktop_config.json` (**Settings → Developer →
    Edit Config**), then restart Claude Desktop:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Codex" icon="terminal">
    Add this entry to `~/.codex/config.toml`:

    ```toml theme={null}
    [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.
  </Tab>

  <Tab title="Cursor" icon="cursor">
    Add this server to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Windsurf" icon="wind">
    Add this server to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code" icon="code">
    Add this server to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

<Info>
  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.
</Info>

***

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

<Note>
  `cloud_instance_connect` returns a short-lived DCV `authToken`, not a durable
  API credential.
</Note>

***

### 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`                                                                                            |

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

***

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