Connect an MCP client

Give your coding agent the Cerulion CLI, a robot workspace, and the rules for using them. cerulion_mcp is a Model Context Protocol server. Your MCP client starts it over stdio, and it drives the cerulion CLI in a workspace you choose: the agent can create and build nodes, wire and validate graphs, run them, inspect topics, record bags and resimulate, and stop the jobs it starts. Its guide tool teaches the agent how Cerulion works — trigger policies, backpressure, queue depth, process groups — before it touches your graph.

cerulion_mcp is proprietary software distributed as signed binaries. The binaries embed first-party Cerulion crates licensed under AGPL-3.0 (cerulion_core, cerulion_macros, native_ros2_messages, used by the bag-analysis tools); the THIRD_PARTY_NOTICES file in each archive lists them with their source revisions and the licence text, and includes Cerulion’s written offer to provide their source code on request to founders@cerulion.com. The cerulion CLI it drives is separate, open-source software that runs as its own process.

Local server or `mcp.cerulion.com`

	Local `cerulion_mcp`	Hosted `https://mcp.cerulion.com/mcp`
Runs	On your laptop or robot, as a stdio child of your client	On Cerulion’s servers
Tools	Workspace, node, graph, topic, bag, resim, and job tools against your `cerulion` CLI, plus bag analysis	Cerulion Cloud instance tools and bag analysis of `https://` bags; no local workspace tools
Needs	The `cerulion` CLI 1.0.0 on the same machine	A Cerulion account (your client signs in with OAuth)

Use the local server to build and run robot code. To connect to the hosted server instead, add its URL to your client:

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

Install the server

Install the Cerulion CLI

The server is tested against cerulion 1.0.0. Install it as described in Installation, then check:

cerulion --version

It prints cerulion 1.0.0. Nodes are shared libraries the CLI loads, so build them with the compiler that built the CLI: rustup toolchain install 1.93.0. Workspaces created with cerulion workspace create pin it in rust-toolchain.toml.

Install cerulion_mcp

Homebrew
Archive

On macOS or Linux:

brew install cerulion-inc/cerulion/cerulion-mcp

Download cerulion-mcp-<version>-<target>.tar.gz for your platform — aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, or aarch64-unknown-linux-gnu — with its .sha256 file. Verify it, then run the bundled installer, which copies cerulion_mcp into ~/.local/bin (or --prefix DIR):

shasum -a 256 -c cerulion-mcp-0.1.0-aarch64-apple-darwin.tar.gz.sha256
tar -xzf cerulion-mcp-0.1.0-aarch64-apple-darwin.tar.gz
./cerulion-mcp-0.1.0-aarch64-apple-darwin/install.sh

On Linux, use sha256sum -c. Unlike the cerulion CLI archives (see Installation), the MCP’s macOS binaries are signed with Cerulion’s Developer ID and notarized, so a browser download needs no xattr step; Gatekeeper checks the notarization online on first launch.

Check the install

cerulion_mcp --version

It prints cerulion-mcp 0.1.0. Run cerulion_mcp --help for every flag and environment variable.

Configure your client

Use absolute paths for the server, the workspace, and the CLI. GUI clients such as Claude Desktop, Cursor, and VS Code do not inherit your shell PATH, so pass --bin or set CERULION_MCP_BIN. Find the paths with:

command -v cerulion_mcp cerulion cargo

node_build and graph_run compile nodes with cargo, which the CLI also finds on PATH. Give a GUI client a PATH whose first entry is the directory that dirname "$(command -v cargo)" prints (~/.cargo/bin with rustup, as in the JSON examples below); otherwise the first build fails with cargo not found. The examples use the Homebrew prefix on Apple Silicon, /opt/homebrew/bin. With Homebrew on Linux it is /home/linuxbrew/.linuxbrew/bin; with the archive installer it is ~/.local/bin.

Claude Code
Codex
Claude Desktop
Cursor
VS Code

claude mcp add --transport stdio cerulion -- \
  /opt/homebrew/bin/cerulion_mcp --workspace /Users/me/robot --bin /opt/homebrew/bin/cerulion

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

[mcp_servers.cerulion]
command = "/opt/homebrew/bin/cerulion_mcp"
args = ["--workspace", "/Users/me/robot", "--bin", "/opt/homebrew/bin/cerulion"]

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

{
  "mcpServers": {
    "cerulion": {
      "command": "/opt/homebrew/bin/cerulion_mcp",
      "args": ["--workspace", "/Users/me/robot"],
      "env": {
        "CERULION_MCP_BIN": "/opt/homebrew/bin/cerulion",
        "PATH": "/Users/me/.cargo/bin:/usr/bin:/bin"
      }
    }
  }
}

Add this server to .cursor/mcp.json:

{
  "mcpServers": {
    "cerulion": {
      "command": "/opt/homebrew/bin/cerulion_mcp",
      "args": ["--workspace", "${workspaceFolder}"],
      "env": {
        "CERULION_MCP_BIN": "/opt/homebrew/bin/cerulion",
        "PATH": "/Users/me/.cargo/bin:/usr/bin:/bin"
      }
    }
  }
}

Add this server to .vscode/mcp.json:

{
  "servers": {
    "cerulion": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/cerulion_mcp",
      "args": ["--workspace", "${workspaceFolder}"],
      "env": {
        "CERULION_MCP_BIN": "/opt/homebrew/bin/cerulion",
        "PATH": "/Users/me/.cargo/bin:/usr/bin:/bin"
      }
    }
  }
}

Flag	Meaning
`--workspace DIR`	The robot workspace and trust boundary. Default: `CERULION_MCP_WORKSPACE`, then the current directory.
`--bin PATH`	The `cerulion` CLI. Default: `CERULION_MCP_BIN`, then an absolute `PATH` entry. A workspace’s `target/` is never searched.
`--release`	Build and run nodes in release mode.
`--allow-outside-workspace`	Let tool paths leave the workspace.

Ask the agent to call workspace_info first — it reports the workspace and the CLI path and version the server resolved — and then guide, the operating rules it should follow. Then try:

Create a node that publishes a counter at 10 Hz and a node that logs it, wire them into a graph, validate it, run it for five seconds, and show the topic rate.

To investigate a recording instead of driving the CLI, an MCP client such as Claude Code, Cursor, or Claude Desktop can also register Hindsight’s MCP server. Hindsight is a separate server, and it is not open source.

Where calls go

Every tool description ends with a Reach: line. The MCP tools reference lists each one.

Reach	Tools
This machine only	Workspace, node (except `node_run`), graph (except `graph_run`), schema, bag, resim, job, and `studio_*` tools; `guide`, `system_help`
Every Cerulion process on this host, not only this workspace’s	`flashback_capture` (every live graph), `system_clean` (the shared iceoryx2 state under `/tmp/iceoryx2`)
Whatever the subcommand reaches (topic and viz verbs use LAN discovery)	`system_cli`
This machine plus the LAN	`graph_run` and `node_run` start a network gateway (off with `network_off: true`). `node_run`, and a graph with no enabled `network:` block, announce every produced topic on the LAN, viewable by any peer without pairing; a graph’s `network:` block limits what leaves to its `egress` list; `topic_*` and `viz_attach` use LAN discovery (off with `no_network: true`)
A robot over the LAN, or public relay servers	`robot_connect`, `robot_pair`
The Cerulion account service	`account_login`
Cerulion Cloud	`cloud_*`, listed only when `CERULION_CLOUD_API_URL` and `CERULION_CLOUD_TOKEN` are set

Security model

The server runs with your user’s permissions. CLI-backed tools run only the cerulion binary it resolved, with argument lists it builds itself. The bag-analysis tools run inside the server instead: they read MCAP bags in the workspace and, when given an https:// source, download it over the internet first. The Cerulion Cloud tools call the Cloud API with your token, and only when it is configured.
The workspace is the trust boundary: every path a tool takes must lie inside it unless you start the server with --allow-outside-workspace. The one exception is the CLI’s own state in ~/.cerulion: account_login stores your session there, and robot_pair writes desk.key and robots.toml there.
Two tools act on the whole host rather than the workspace: flashback_capture asks every live Cerulion graph on the machine to write its recent history, and system_clean wipes the iceoryx2 shared-memory state that every Cerulion process shares.
Deletes need confirm: true. system_clean and bag_migrate preview by default. graph_run rewrites the graph file only when persist_partition is true.
The server sends no telemetry of its own.

How tools behave

Long-running verbs — graph_run, node_run, bag_play, bag_record, topic_watch — return a job ID instead of blocking. Poll it with job_status and job_logs, and end it with job_stop. Jobs run in their own process groups, are scoped to the workspace that started them, and stop when the server exits.
A tool that could not do its job returns isError: true with text that starts with one ERROR: line naming the fix; the CLI’s stderr is in the structured result.
resim_run runs cerulion bag play <bag> --resim all and caches verified outcomes under .cerulion-mcp/runs. fresh: false is a cache hit, not a failure.

Troubleshooting

cerulion not found or the wrong version. Call workspace_info. Set --bin or CERULION_MCP_BIN to an absolute path to cerulion 1.0.0.
A node build fails with a Rust version or ABI error. Build with the CLI’s compiler: rustup toolchain install 1.93.0, and keep the workspace’s rust-toolchain.toml.
ERROR: ... outside the workspace. Pass paths inside --workspace, or start the server with --allow-outside-workspace.
The client shows no tools. Run the configured command in a terminal. It waits silently on stdin; anything printed to stderr is the reason, and CERULION_MCP_LOG=debug adds detail.
The CLI asks you to log in. Run account_login, or cerulion login in a terminal, once per machine.

Upgrade and uninstall

Upgrade with brew upgrade cerulion-mcp, or run a newer archive’s install.sh, then restart your client. Uninstall with brew uninstall cerulion-mcp, or delete ~/.local/bin/cerulion_mcp, and remove the cerulion entry from your client config. A workspace may hold a .cerulion-mcp/ directory with cached resim runs; delete it when you no longer need them.

Get started

Concepts

Guides

Studio and Hindsight

Reference

Community

Local server or `mcp.cerulion.com`

Install the server

Configure your client

Where calls go

Security model

How tools behave

Troubleshooting

Upgrade and uninstall

​Local server or mcp.cerulion.com

​Install the server

​Configure your client

​Where calls go

​Security model

​How tools behave

​Troubleshooting

​Upgrade and uninstall

Local server or `mcp.cerulion.com`

Install the server

Configure your client

Where calls go

Security model

How tools behave

Troubleshooting

Upgrade and uninstall