The Checkly MCP Server uses bearer-token authentication and Checkly account authorization together. Session permissions decide which tools are visible to your MCP client. Checkly account membership, role, and feature entitlements decide whether a specific tool call can operate on an account.
Authentication
The MCP Server accepts two types of bearer tokens for https://api.checklyhq.com/mcp:
- OAuth bearer tokens from Checkly-approved MCP clients.
- Checkly user API keys starting with
cu_..., and service API keys starting with sv_..., sent as Authorization: Bearer <checkly-api-key>.
OAuth is recommended for interactive clients. The public MCP Server only supports Checkly-approved OAuth clients. Checkly rejects clients that attempt to use Dynamic Client Registration (DCR). See supported OAuth clients or set up an API key.
Checkly maps OAuth tokens and user API keys to a Checkly user, then loads that user’s account memberships and account context for tool calls. Service API keys map to the key’s configured account and role.
API keys are long-lived credentials. Use them when OAuth is unavailable or a workflow needs a service identity. Store keys securely and rotate them when they are no longer needed.
Session permissions
| Permission | Description |
|---|
checkly:account:read | Read your Checkly account membership and status |
checkly:account:invite | Invite members to your Checkly account |
checkly:checks:read | List checks, their status and results |
checkly:checks:run | Trigger Checkly checks and on-demand test sessions |
checkly:incidents:read | Read your Checkly incidents |
checkly:incidents:write | Create and update your Checkly incidents |
checkly:environment-variables:read | Read your Checkly account environment variables (secret values excluded) |
checkly:environment-variables:write | Create, update and delete your Checkly account environment variables |
checkly:status-pages:read | Read your Checkly status pages |
checkly:rca:read | Read your Checkly root cause analyses |
checkly:rca:run | Run Checkly root cause analysis for your account |
checkly:test-sessions:read | Read your Checkly test sessions |
checkly:assets:read | Read your Checkly assets |
checkly:account:invite, so invite-account-member is only available with OAuth.
Tools are filtered from tools/list when the MCP session does not include the required permission. Tool calls are also rejected if the session lacks the required permission.
Account context
Most tools operate on one Checkly account. You can select a specific account in your prompt or pin an account in your MCP client configuration. See Select an account for setup examples.
Accounts that require mTLS are not available through the public MCP Server.
Role checks
Some tools require both an MCP session permission and a Checkly account role:
| Tool or action | Additional account access required |
|---|
invite-account-member | Owner or Admin |
create-account-environment-variable | Write access |
update-account-environment-variable | Write access |
trigger-checks | Run access |
trigger-root-cause-analysis | Run access |
| Status page incident writes | Access required by the underlying incident action |
Write-action safety
Some MCP tools create side effects:
invite-account-member sends an invite email and is not idempotent.trigger-checks consumes check-run execution quota.trigger-root-cause-analysis consumes RCA invocation quota.create-status-page-incident, update-status-page-incident, and resolve-status-page-incident can notify subscribers and are not idempotent.- Environment variable write tools can create or replace account-level variables and secrets.
Review write tool calls in your MCP client before approving them.
Secrets
MCP read tools never reveal Checkly secret values. Secret values are returned as null.
When you create or update a secret through MCP, Checkly encrypts the value and does not echo it back in the tool response. 
