Troubleshooting
Use this table when icuvisor does not start, an MCP client cannot see tools, or a connection works differently after an upgrade.
| Symptom | Likely cause | Fix |
|---|---|---|
| macOS says the app is from an unidentified developer | Gatekeeper could not validate the app signature or notarization. | Verify the release with the commands in Install on macOS. Do not override Gatekeeper until the signature checks pass. |
MCP client reports missing intervals.icu API key | The API key is not in the OS keychain, INTERVALS_ICU_API_KEY, or legacy config fallback. | Run icuvisor setup, or follow API key setup. Confirm the macOS Keychain item with security find-generic-password -s icuvisor -a intervals-icu-api-key >/dev/null. |
MCP client reports missing athlete ID or invalid athlete ID | No non-secret athlete selector was provided, or it is malformed. | Set INTERVALS_ICU_ATHLETE_ID to 12345 or i12345, or provide athlete_id in the JSON config file. See the config file reference. |
| The assistant says a newly added or fixed tool is still missing after upgrade | The MCP client cached the old tool catalog for the current conversation. | Start a new conversation or reconnect the MCP client. If _meta.schema_changed appears, follow After upgrading. |
| HTTP client cannot connect from another machine on the LAN | icuvisor binds to 127.0.0.1:8765 by default, which is reachable only from the same machine. | Read HTTP transport. Only bind a LAN IP if you accept that anyone who can reach it can call the unauthenticated MCP server. |
| HTTP startup fails with an invalid bind address | The bind address is not an explicit IP address and port. | Use a value like 127.0.0.1:8765 or 192.168.1.10:8765; hostnames are not accepted. |
| Linux reports key not found or cannot reach the keychain | libsecret/Secret Service is missing, locked, or unavailable in a headless session. | Install/start your desktop secret-service provider, or use secret-tool store --label='icuvisor intervals.icu API key' service icuvisor username intervals-icu-api-key. For headless fallback, set INTERVALS_ICU_API_KEY deliberately and protect the service environment. |
| Claude Desktop or Claude Code cannot start icuvisor | The command path is wrong or JSON syntax is invalid. | Confirm /Applications/icuvisor.app/Contents/MacOS/icuvisor version works. For Claude Desktop, run plutil -lint "$HOME/Library/Application Support/Claude/claude_desktop_config.json". For Claude Code, validate .mcp.json and restart the session. |
| A delete tool is missing | ICUVISOR_DELETE_MODE is not full, the toolset/coach ACL hides it, or the client cached an old catalog. | Check Safety modes and toolset tiers, restart icuvisor after changing env vars, and start a new client conversation. |