docs: document MCP API key auth (#425)

Author: thebiglabasky

ai/mcp-server.mdx

@@ -1,10 +1,10 @@
 ---
 title: 'Checkly MCP Server'
-description: 'Connect supported AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.'
+description: 'Connect MCP clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.'
 sidebarTitle: 'Overview'
 ---
 
-The Checkly MCP Server lets supported AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation.
+The Checkly MCP Server lets MCP clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation.
 
 Use the production MCP endpoint in your client:
 
@@ -13,7 +13,7 @@ https://api.checklyhq.com/mcp
 ```
 
 <Warning>
-The Checkly MCP Server only supports Checkly-approved OAuth clients listed in setup. Clients that use Dynamic Client Registration (DCR) are rejected. See [setup requirements](/ai/mcp-server/setup) for supported clients and details.
+OAuth is the recommended way to connect. The OAuth flow only supports Checkly-approved clients listed in setup. API-key authentication is available for non-interactive clients that can send custom headers, but you are responsible for protecting and rotating the key.
 </Warning>
 
 Use it when your agent needs live Checkly account context, check status, check results, test sessions, root cause analyses, result assets, status pages, incidents, account environment variables, or when it needs to trigger existing checks.
@@ -40,10 +40,10 @@ Before connecting an MCP client, ensure you have:
 
 - A Checkly user account.
 - Access to the Checkly account you want the MCP client to use.
-- A [supported MCP client](/ai/mcp-server/setup#supported-clients).
+- A [supported OAuth MCP client](/ai/mcp-server/setup#supported-clients), or an MCP client that can send custom HTTP headers for API-key authentication.
 </Accordion>
 
-[Add the Checkly MCP endpoint to your client](/ai/mcp-server/setup), complete the OAuth flow, then ask your client to verify the connection:
+[Add the Checkly MCP endpoint to your client](/ai/mcp-server/setup), complete the OAuth flow, then ask your client to verify the connection. If your client cannot complete OAuth but can send custom headers, configure API-key authentication instead.
 
 ```text title="Prompt" wrap
 Use Checkly to show which accounts I can access.
@@ -85,7 +85,7 @@ Create a major status page incident for the API outage, but do not notify subscr
 
 ## MCP, Skills, and CLI
 
-MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for a quick, OAuth-based connection from a supported client. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project.
+MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for a quick OAuth-based connection from a supported client. Use API-key authentication only when OAuth is not practical for a non-interactive workflow. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project.
 
 See [Skills, MCP, and the CLI](/ai/overview#skills-mcp-and-the-cli) for a full comparison of when to use each.
 

ai/mcp-server/security-and-permissions.mdx

@@ -4,17 +4,24 @@ description: 'Understand how the Checkly MCP Server authenticates users, filters
 sidebarTitle: 'Security & permissions'
 ---
 
-The Checkly MCP Server uses OAuth and Checkly account authorization together. OAuth 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.
+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 Auth0-issued bearer tokens for `https://api.checklyhq.com/mcp`. Your MCP client completes the OAuth flow and sends the token with requests to the MCP endpoint.
+The MCP Server accepts two types of bearer tokens for `https://api.checklyhq.com/mcp`:
 
-The public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [supported clients](/ai/mcp-server/setup#supported-clients) for setup details.
+- 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>`.
 
-Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls.
+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)](https://datatracker.ietf.org/doc/html/rfc7591). See [supported clients](/ai/mcp-server/setup#supported-clients) for setup details.
 
-## OAuth permissions
+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.
+
+<Warning>
+API keys are long-lived credentials. Use API-key authentication only when OAuth is not practical, store keys securely, and rotate them when they are no longer needed.
+</Warning>
+
+## Session permissions
 
 | Permission | Description |
 | --- | --- |
@@ -32,6 +39,8 @@ Checkly maps the token subject to a Checkly user, then loads that user's 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
@@ -42,9 +51,11 @@ Most tools operate on one Checkly account. You can select a specific account in
 Accounts that require mTLS are not available through the public MCP Server.
 </Warning>
 
+Blocked accounts can be inspected with read-only tools, but write, run, and admin tools are rejected.
+
 ## Role checks
 
-Some tools require both an OAuth permission and a Checkly account role:
+Some tools require both an MCP session permission and a Checkly account role:
 
 | Tool or action | Additional account access required |
 | --- | --- |

ai/mcp-server/setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Set up the Checkly MCP Server'
-description: 'Configure a supported MCP client to connect to the Checkly MCP Server over Streamable HTTP.'
+description: 'Configure OAuth or API-key authentication for the Checkly MCP Server over Streamable HTTP.'
 sidebarTitle: 'Setup'
 ---
 
@@ -11,12 +11,12 @@ https://api.checklyhq.com/mcp
 ```
 
 <Warning>
-The Checkly MCP Server only supports the clients listed below. Clients that use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) are rejected.
+OAuth is the recommended way to connect. The OAuth flow only supports the clients listed below. Clients that use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) are rejected.
 </Warning>
 
 ## Supported clients
 
-The public Checkly MCP Server currently supports these clients:
+The public Checkly MCP Server currently supports OAuth for these clients:
 
 | Client | Support status | Notes |
 | --- | --- | --- |
@@ -29,7 +29,7 @@ The public Checkly MCP Server currently supports these clients:
 | Cursor | Supported | Uses Checkly's static Cursor MCP OAuth client. Configure `.cursor/mcp.json` or `~/.cursor/mcp.json`. |
 | VS Code | Supported | Configure `.vscode/mcp.json` or your VS Code user profile. |
 
-Supported clients must use a Checkly-approved OAuth client in Auth0. Most supported clients use [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Cursor, Devin CLI, and OpenCode use Checkly's static MCP OAuth clients. Clients that rely on DCR are not supported.
+Supported OAuth clients must use a Checkly-approved OAuth client. Most supported clients use [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Cursor, Devin CLI, and OpenCode use Checkly's static MCP OAuth clients. Clients that rely on DCR are not supported.
 
 If you want Checkly to support another compatible client, [share feedback or requests](https://feedback.checklyhq.com).
 
@@ -51,6 +51,39 @@ claude mcp add --transport http checkly https://api.checklyhq.com/mcp
 
 Start a Claude Code session and complete the OAuth flow when prompted.
 
+## API key authentication
+
+<Accordion title="Before you begin">
+Before using API-key authentication, ensure you have:
+
+- An MCP client that can send custom HTTP headers.
+- A current Checkly user API key starting with `cu_...`, or a current service API key starting with `sv_...`.
+- A secure place to store the key outside version control.
+</Accordion>
+
+Use API-key authentication only when OAuth is not practical for your workflow. Send the API key in the `Authorization` header:
+
+```bash Terminal
+claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "Authorization: Bearer <checkly-api-key>"
+```
+
+For clients that use an `mcpServers` JSON configuration, add the header to the Checkly server entry:
+
+```json mcp.json
+{
+  "mcpServers": {
+    "checkly": {
+      "url": "https://api.checklyhq.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <checkly-api-key>"
+      }
+    }
+  }
+}
+```
+
+Service API keys are limited to the key's configured account and role. Deprecated account API keys and old `sk_...` service-key formats are rejected. API-key sessions cannot use the `invite-account-member` tool.
+
 ## Devin CLI
 
 Use this configuration:
@@ -165,7 +198,7 @@ Restart VS Code after changing the configuration.
 
 ## Known client limitations
 
-Some MCP clients support remote MCP servers but do not work with the public Checkly MCP Server yet. If your preferred compatible client is missing, [share feedback or requests](https://feedback.checklyhq.com).
+Some MCP clients support remote MCP servers but do not work with the public Checkly MCP Server OAuth flow yet. If your preferred compatible client is missing, [share feedback or requests](https://feedback.checklyhq.com).
 
 ### Cline
 
@@ -226,4 +259,4 @@ Then verify tool access:
 Use Checkly to list the tools available to this session.
 ```
 
-The visible tools depend on the OAuth permissions granted to your MCP session. See [Security and permissions](/ai/mcp-server/security-and-permissions) for details.
+The visible tools depend on the permissions granted to your MCP session. See [Security and permissions](/ai/mcp-server/security-and-permissions) for details.

ai/mcp-server/tools.mdx

@@ -6,7 +6,7 @@ sidebarTitle: 'Tools'
 
 This reference reflects the current MCP Server v1 tool surface. It is not a roadmap or a commitment to future tools.
 
-Each tool is shown only when the MCP session has the required OAuth permission. Some write tools also require a matching Checkly account role, such as Admin or Read & Write.
+Each tool is shown only when the MCP session has the required permission. Some write tools also require a matching Checkly account role, such as Admin or Read & Write.
 
 ## Account tools
 
@@ -15,7 +15,7 @@ Each tool is shown only when the MCP session has the required OAuth permission.
 | `whoami` | Read | Return the authenticated user and account memberships visible to the MCP session. |
 | `get-account-entitlements` | Read | Return the resolved account plan and feature entitlement state. |
 | `list-account-members` | Read | List account members and pending invites. |
-| `invite-account-member` | Write | Invite a user to the resolved account. Requires Owner or Admin access, sends an invite email, and is not idempotent. |
+| `invite-account-member` | Write | Invite a user to the resolved account. OAuth-only. Requires Owner or Admin access, sends an invite email, and is not idempotent. |
 | `prepare-local-check-authoring` | Read | Return an account-aware runbook for creating, testing, and deploying check code with the local Checkly CLI. |
 
 Example prompts:

ai/mcp-server/troubleshooting.mdx

@@ -8,8 +8,8 @@ sidebarTitle: 'Troubleshooting'
 Before troubleshooting, confirm:
 
 - Your MCP client is configured with `https://api.checklyhq.com/mcp`.
-- Your MCP client is in the [supported clients list](/ai/mcp-server/setup#supported-clients).
-- You completed the OAuth login flow.
+- Your OAuth client is in the [supported clients list](/ai/mcp-server/setup#supported-clients), or your API-key client can send custom HTTP headers.
+- You completed the OAuth login flow, or configured an `Authorization: Bearer <checkly-api-key>` header for API-key authentication.
 - You restarted your MCP client after editing configuration.
 - Your Checkly user has access to the account you want to use.
 </Accordion>
@@ -18,34 +18,37 @@ Before troubleshooting, confirm:
 
 If your client reports that authentication is required or invalid:
 
-1. Re-run your client's MCP login flow.
-2. Confirm the endpoint is exactly `https://api.checklyhq.com/mcp`.
-3. Remove stale Checkly MCP credentials from the client if it keeps reusing an old token.
-4. Reconnect and call `whoami`.
+1. If you use OAuth, re-run your client's MCP login flow.
+2. If you use API-key authentication, confirm the header is exactly `Authorization: Bearer <checkly-api-key>`.
+3. Confirm the endpoint is exactly `https://api.checklyhq.com/mcp`.
+4. Remove stale Checkly MCP credentials from the client if it keeps reusing an old token.
+5. Reconnect and call `whoami`.
+
+For API-key authentication, use a current `cu_...` user API key, or a current `sv_...` service API key. Deprecated account API keys and old `sk_...` service-key formats are rejected.
 
 <Warning>
-If the browser login page shows an Auth0 "Something went wrong" error, contact [Checkly Support](mailto:support@checklyhq.com). Include the MCP client you used, the Checkly account you were trying to access, and the approximate time of the error.
+If the browser login page shows a "Something went wrong" error, contact [Checkly Support](mailto:support@checklyhq.com). Include the MCP client you used, the Checkly account you were trying to access, and the approximate time of the error.
 </Warning>
 
 ## OAuth registration fails
 
-The Checkly MCP Server only supports clients that Checkly has approved in Auth0. Checkly does not support Dynamic Client Registration (DCR).
+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 clients list](/ai/mcp-server/setup#supported-clients). Unsupported clients cannot connect to the public Checkly MCP Server, even if they support remote MCP servers.
+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 clients list](/ai/mcp-server/setup#supported-clients). Unsupported OAuth clients cannot complete the Checkly OAuth flow, even if they support remote MCP servers.
 
 ## No tools are listed
 
-Visible tools depend on the OAuth permissions granted to the MCP session. If no tools appear:
+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 and complete OAuth again.
+3. Reconnect and complete OAuth again, 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 OAuth permission. For example:
+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.
@@ -54,6 +57,8 @@ Each tool requires an OAuth permission. For example:
 
 See [MCP tools](/ai/mcp-server/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](https://feedback.checklyhq.com) so we can understand the workflow your agent was trying to complete.
 
 ## The tool asks for an account
@@ -97,5 +102,6 @@ Before approving write tool calls, check:
 
 Some browser-based clients require CORS support and may handle OAuth differently from command-line clients. If a browser-based client cannot connect:
 
-1. Confirm the client is in the [supported clients list](/ai/mcp-server/setup#supported-clients).
-2. Try another supported client, such as Claude Code.
+1. If you use OAuth, confirm the client is in the [supported clients list](/ai/mcp-server/setup#supported-clients).
+2. If you use API-key authentication, confirm the client sends custom headers with remote MCP requests.
+3. Try another supported client, such as Claude Code.