Troubleshooting

Troubleshooting

No frames / tools return empty / CLI commands time out

By far the most common issue, and almost always the same root cause:

python-can's virtual interface backend does not reliably share bus state across separate OS processes (this is especially consistent on Windows; less consistent but still not guaranteed on Linux). It's in-process Python state, not a real OS-level bus — a virtual bus created in one process's interpreter is invisible to another process's interpreter, even with identical interface/channel settings.

Practical implications:

• mcp-can simulate in one terminal and mcp-can server in another may not see each other's traffic, even though both default to virtual/bus0.
• Any one-shot CLI command (frames, monitor, snapshot, obd-request, diag-request, fault) run as its own process will not reach a simulator running in a different process either — the CLI command's own bus connection is just as isolated.

Fix: run the simulator and whatever needs to see its traffic in the same process. mcp-can demo does exactly this (simulator on a background thread, server in the foreground) and is the recommended way to actually see data flow. If you need the CLI to reach a demo process's simulator, you currently can't — there's no cross-process control channel except the ones purpose-built for it (fault injection uses one; general CLI commands don't). Either drive everything through the MCP tools of that same demo process, or accept that separate-process CLI commands won't see it.

If you're on Linux and want real cross-process sharing, use socketcan with an actual vcan0 interface instead of virtual — see Docker and Deployment.

Docker: dashboard/tools show no traffic

Same root cause as above, one level up. See Docker and Deployment — both the single-container image's current CMD (two separate process invocations via shell &) and the compose setup (two separate containers) are subject to the same cross-process limitation.

DBC missing / "No message named X found"

Set MCP_CAN_DBC_PATH, or place vehicle.dbc in the working directory you're running mcp-can from. dbc.py::load_dbc is lru_cached, so if you change the DBC file on disk mid-session, a long-running server won't pick up the change without a restart.

streamable-http transport fails immediately

Your installed mcp package predates its support — the server logs a clear error and exits rather than crashing on a raw SDK traceback. Either set MCP_CAN_MCP_TRANSPORT=sse, or pip install -U mcp (staying below 2.0.0 — see Installation for why that upper bound exists).

mcp-can fault <preset> (or obd-request/diag-request) says "no ack"/times out

Same root cause as the first section: the fault/obd-request/diag-request commands run as their own process and need a simulator sharing that same process's bus. If you started the simulator with mcp-can demo in another terminal, that's a different process — the command has nothing to talk to. Run these against a simulator in the same process, or drive the equivalent MCP tool (activate_fault_scenario/send_obd_request/send_diagnostic_request) through an MCP client connected to that demo process's server instead.

CORS / browser MCP client can't connect

Check MCP_CAN_CORS_ALLOW_ORIGINS — see Configuration. The default ["*"] should work for most local tooling (MCP Inspector, etc.); if you've narrowed it to specific origins for a real deployment, make sure the connecting origin is actually in that list.

Docker networking

Make sure port 6278 (the MCP server) is exposed/published from whatever container is running it — see the docker run -p/compose ports examples in Docker and Deployment.