Troubleshooting

Start with the CLI

Use Node.js 24 or newer. If status succeeds, customer authentication and API reachability work; focus on the MCP client configuration.

node --version
npx -y @coldvio/[email protected] status
npx -y @coldvio/[email protected] config path

The agent cannot see Coldvio tools

• Restart the MCP client after changing its configuration.
• Confirm the command is npx with args -y, @coldvio/cli, mcp.
• Run the same npx command in a terminal to surface startup errors.
• Remove duplicate Coldvio server entries and check the client's MCP logs.

Browser login does not return

• Keep the terminal process running while the browser is open.
• Use the exact browser URL printed by the CLI if automatic opening fails.
• Do not replace 127.0.0.1 with localhost or copy the callback to another device.
• Start login again if the two-minute code has expired.

API errors

• 401 — log in again on the customer-controlled device.
• 403 — the token has the wrong audience or lacks the required scope.
• 404 — the resource does not exist or is not owned by this customer.
• 409 — refresh the resource; its state changed before the operation.
• 429 — reduce concurrency and retry with exponential backoff.

Simultaneous login on one installation

The beta enforces one active token per customer installation. If two login exchanges race, exchange fails with the generic invalid, expired, or already-used code response. Stop the other attempt and run login again.

Report an issue safely

Include CLI version, Node version, operating system, MCP client, command name, timestamp, and sanitized error text. Remove tokens, contact data, message content, callback codes, and full request bodies before sharing diagnostics.