Agent troubleshooting
Agent failures usually belong to one of five layers: client configuration, authentication, MCP transport, project authorization, or the underlying Runtime/tool operation.
Connection checks
- Confirm the configured command or endpoint matches the chosen CLI or Desktop connection.
- Restart the MCP client after changing its configuration.
- Verify credentials and account/project access without copying secrets into chat or logs.
- Confirm Desktop is running with the intended project open when using a Desktop connection.
- Refresh tool discovery and check that the required tool is allowed.
If a tool connects but fails, read its structured error. A missing file can indicate the wrong project root; an execution error can be valid Runtime behavior; a denied call can be tool policy rather than transport failure. Compare the same operation in Desktop or the CLI to isolate the layer.
For intermittent failures, capture client name and version, Agent version, connection type, time, sanitized logs, tool name, error code, and a minimal reproduction. Revoke credentials that may have been exposed during debugging and avoid publishing connection tokens in issue reports.