Skip to main content
Before troubleshooting, confirm:
  • Your MCP client is configured with https://api.checklyhq.com/mcp.
  • You chose an authentication method supported by your client.
  • You restarted your MCP client after editing its configuration.
  • Your Checkly user or service API key can access the account you want to use.

​
Authentication

​
OAuth sign-in fails

If your client reports that authentication is required or the browser sign-in does not complete:
  1. Confirm the client is in the supported OAuth clients list.
  2. Confirm the endpoint is exactly https://api.checklyhq.com/mcp.
  3. Re-run your client’s MCP login or authentication flow.
  4. Remove stale Checkly MCP credentials from the client if it keeps reusing an old token.
  5. Reconnect and call whoami.
If the browser login page shows a “Something went wrong” error, contact Checkly Support. Include the MCP client, the Checkly account, and the approximate time of the error.

​
OAuth client registration fails

The Checkly MCP Server only supports Checkly-approved OAuth clients. Checkly does not support Dynamic Client Registration (DCR). If your client reports a dynamic registration error, a failed client registration, or never opens the expected OAuth flow, confirm that the client is in the supported OAuth clients list. A client can support remote MCP servers and still be incompatible with the Checkly OAuth flow. If your client can send custom headers, use API-key authentication as a fallback.

​
An API key is rejected

If your client reports a missing or invalid bearer token:
  1. Confirm the header is exactly Authorization: Bearer <checkly-api-key>.
  2. Use a current cu_... user API key or sv_... service API key. Deprecated account API keys and old sk_... service-key formats are rejected.
  3. Confirm the key has not been revoked.
  4. Confirm the client sends the header with remote MCP requests.
  5. Reconnect and call whoami.
For a user API key, confirm the user still belongs to the target account. For a service API key, confirm the key belongs to the target account and has the role needed for the action. If your client reads the bearer token from an environment variable, start the client from an environment where that variable is set. See Set up with an API key for client examples and Creating an API key in Checkly for key management.

​
Tools and permissions

​
No tools are listed

Visible tools depend on the permissions granted to the MCP session. If no tools appear:
  1. Use your MCP client’s refresh tools option.
  2. Restart the client if the tools list still does not update.
  3. Reconnect with OAuth, or confirm your API-key header is still configured.
After the tools list refreshes, call whoami or ask Checkly which accounts you can access to verify the connection.

​
A specific tool is missing

Each tool requires an MCP session permission. For example:
  • Check status and results require permission to list checks, their status, and results.
  • Test sessions require permission to read your Checkly test sessions.
  • Asset tools require permission to read Checkly assets plus the related result permission.
  • Incident write tools require permission to create and update your Checkly incidents.
See MCP tools for the full tool list. The invite-account-member tool is not available with API-key authentication. Reconnect with OAuth if you need to invite account members through MCP. If the tool you expected is not part of the current MCP Server, share feedback or requests so we can understand the workflow your agent was trying to complete.

​
A tool call is denied

Tool visibility and Checkly account access are separate checks. A tool can be visible but reject a call when the selected account does not include the required feature or the authenticated user or service API key has an insufficient role. Confirm the target account and the role returned by whoami. User API keys inherit the user’s role. Service API keys use the account and role selected when the key was created. See Security and permissions for the access required by write and run actions.

​
Account selection

​
A tool asks for an account

OAuth sessions and user API keys can access multiple Checkly accounts. Ask your client:
Prompt
To always use the same account, set the X-Checkly-Account header in your MCP server configuration. See Select an account. Service API keys are already scoped to one account. If a service-key session reports that it cannot access the account in X-Checkly-Account, remove the header or set it to the account configured on the key.

​
Local check authoring

​
The MCP server cannot create or deploy check code

The MCP server runs remotely and cannot access your local project files. It cannot author, bundle, test, or deploy check code. Ask for a CLI handoff instead:
Prompt
Then run the returned Checkly CLI steps in your local project.

​
Write actions

​
A write tool did more than expected

Some write tools are not idempotent. Retrying a call can create another invite, another incident, or another incident update. If a write tool changed more than you expected, contact Checkly Support. Include the MCP client, the Checkly account, the tool name, and the approximate time of the action. Before approving write tool calls, check:
  • The target account ID.
  • The target status page or check ID.
  • Whether subscribers will be notified.
  • Whether the action consumes check-run or RCA quota.

​
Browser-based clients

​
A browser client or web IDE cannot connect

Some browser-based clients require CORS support and may handle OAuth differently from command-line clients. If a browser-based client cannot connect:
  1. If you use OAuth, confirm the client is in the supported OAuth clients list.
  2. If you use an API key, confirm the client sends custom headers with remote MCP requests.
  3. Try another supported client, such as Claude Code.