Install the CANarchy MCP server in an agent client

canarchy mcp serve exposes the CLI as an MCP stdio server. Any MCP-capable client can call CANarchy tools the same way it calls its own built-in tools. This page covers the canonical install paths.

For the agent-side workflows themselves (which tools to call, the event-stream contract, security guidance), see the Agent Guide and the Command Spec.

Prerequisites

Confirm canarchy is on your PATH and the MCP server starts cleanly:

canarchy --version
canarchy mcp serve --help

If either fails, follow the Getting Started install steps first. A clean canarchy doctor --text run is a fast way to verify the local environment before wiring it into a client.

Quick install with canarchy mcp install

Instead of editing config files by hand, let CANarchy write the mcpServers.canarchy block for you:

# Preview the change without touching disk
canarchy mcp install --client claude-desktop --dry-run

# Write it (prompts for confirmation; --ack skips the prompt)
canarchy mcp install --client claude-desktop
canarchy mcp install --client claude-code --ack

The helper:

• detects the client config path per platform (--config-path overrides it),
• merges the canarchy entry into mcpServers without disturbing other servers,
• refuses to clobber a different existing canarchy entry (MCP_INSTALL_CONFLICT) and leaves unrelated or invalid configs untouched (MCP_INSTALL_INVALID_CONFIG, MCP_INSTALL_DIR_MISSING),
• and accepts --command when canarchy lives in a venv rather than on PATH (e.g. --command /path/to/.venv/bin/canarchy).

--client claude-desktop targets the platform path below; --client claude-code writes a project-scoped .mcp.json in the current directory. The hand-edit paths below remain the canonical fallback.

Claude Desktop

Edit Claude Desktop's MCP config file:

Platform	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add a canarchy entry under mcpServers:

{
  "mcpServers": {
    "canarchy": {
      "command": "canarchy",
      "args": ["mcp", "serve"]
    }
  }
}

If canarchy is installed inside a project venv rather than on the system PATH, give the absolute path to the binary:

{
  "mcpServers": {
    "canarchy": {
      "command": "/path/to/.venv/bin/canarchy",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Claude Desktop. The CANarchy tools will appear in the tool picker.

Claude Code

Claude Code reads MCP server entries from project-scoped or user-scoped configuration. The block shape is the same as Claude Desktop:

{
  "mcpServers": {
    "canarchy": {
      "command": "canarchy",
      "args": ["mcp", "serve"]
    }
  }
}

Drop the block into the appropriate Claude Code config file. The CLI also accepts MCP servers via:

claude mcp add canarchy canarchy mcp serve

(Refer to the Claude Code documentation for the current command surface of your installed version.)

Other MCP clients

Any client that speaks MCP over stdio can run CANarchy with the same command. A generic configuration looks like:

mcp_servers:
  canarchy:
    command: canarchy
    args:
      - mcp
      - serve

Cursor, Continue, Cline, and similar editor integrations follow the same pattern. The only requirement is that the client launches canarchy mcp serve as a subprocess and speaks JSON-RPC on stdio.

Verify the integration

Ask the agent to call CANarchy against one of the in-repo fixtures:

Run canarchy capture-info on tests/fixtures/j1939_heavy_vehicle.candump and summarise the result.

A correctly wired-up client invokes the capture_info MCP tool and returns the canonical envelope. The doctor tool is the fastest end-to-end smoke check because it requires no fixture:

Run canarchy doctor and report any warnings.

Configuration tips

• Per-project canarchy with uv. If the agent should always pick up a specific project's editable install, point command at uv and pass ["run", "canarchy", "mcp", "serve"] as args, with cwd set to the project root. Some clients support cwd directly; otherwise wrap in a small launcher script.
• Active-transmit safety. Active MCP tools such as send, generate, gateway, replay, sequence_replay, and the fuzz_* tools carry an MCP-side gate: every call must supply ack_active=true, otherwise the response is ACTIVE_TRANSMIT_REQUIRES_ACK and the underlying command is never invoked. dry_run defaults to true for agent-initiated calls (per docs/design/active-transmit-safety.md REQ-ATS-13), so the agent plans the workflow safely unless the operator explicitly passes dry_run=false.
• Logging. The MCP server logs to stderr. The agent client typically surfaces stderr in its diagnostics pane; check there first when a tool call misbehaves.

Troubleshooting

Symptom	Likely cause	Fix
Tools never appear in the client	Wrong command path	Run which canarchy and use the absolute path in the config.
INVALID_ARGUMENTS for known-good calls	Client passes wrong argv shape	Compare against the MCP tool inputSchema; canarchy mcp serve --help documents the bridging contract.
Tools error with DBC_CACHE_MISS	opendbc cache empty	Run canarchy dbc cache refresh --provider opendbc once locally; the agent then has cached data to read.
python-can import errors at startup	Missing optional dependency	Re-run uv sync in the project, or pipx install canarchy for a global install.

canarchy doctor is the canonical first stop for environment problems; each non-ok check ships a copy-pasteable remediation hint.

Where to go next

• Agent Guide — agent-side workflows and policies.
• Command Spec — every CLI command, mirrored as MCP tools where applicable.
• Cookbook: Wire CANarchy into Claude Desktop or Claude Code — the short version of this page.