MCP security and permissions

Understand how the Checkly MCP Server authenticates users, filters tools by permission, handles account context, and protects write actions.

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

OAuth sessions use the permissions granted by the OAuth flow. API-key sessions receive all permissions listed above except 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.

Blocked accounts can be inspected with read-only tools, but write, run, and admin tools are rejected.

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.