From d52b28df3a9c1d745417230376aff21f5c861fc0 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Fri, 10 Jul 2026 16:12:37 +0200 Subject: [PATCH] Improve MCP docs setup and auth flow --- ai/mcp-server.mdx | 8 +- ai/mcp-server/security-and-permissions.mdx | 6 +- ai/mcp-server/setup.mdx | 269 ++++++++++++++------- ai/mcp-server/tools.mdx | 1 + ai/mcp-server/troubleshooting.mdx | 89 ++++--- 5 files changed, 249 insertions(+), 124 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 5e299b32..8b05f873 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -14,7 +14,7 @@ https://api.checklyhq.com/mcp ``` -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. +OAuth is the recommended way to connect. The OAuth flow only supports Checkly-approved clients listed in setup. User and service API keys are available for clients that can send custom headers when OAuth is unavailable or a workflow needs a stable service identity. 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. @@ -41,10 +41,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 OAuth MCP client](/ai/mcp-server/setup#supported-clients), or an MCP client that can send custom HTTP headers for API-key authentication. +- A [supported OAuth MCP client](/ai/mcp-server/setup#supported-oauth-clients), or an MCP client that can send custom HTTP headers for API-key authentication. -[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. +[Choose an authentication method and add the Checkly MCP endpoint to your client](/ai/mcp-server/setup#choose-an-authentication-method). Complete OAuth or configure an API-key header, then ask your client to verify the connection. ```text title="Prompt" wrap Use Checkly to show which accounts I can access. @@ -86,7 +86,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 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. +MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for quick access to live Checkly data and account actions. OAuth is the recommended connection method; use an API key when OAuth is unavailable or when automation needs an account-scoped service identity. 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. diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index bada8988..636c240b 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -14,12 +14,12 @@ The MCP Server accepts two types of bearer tokens for `https://api.checklyhq.com - 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 `. -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 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 OAuth clients](/ai/mcp-server/setup#supported-oauth-clients) or [set up an API key](/ai/mcp-server/setup#set-up-with-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 API-key authentication only when OAuth is not practical, store keys securely, and rotate them when they are no longer needed. +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 @@ -46,7 +46,7 @@ Tools are filtered from `tools/list` when the MCP session does not include the r ## 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 [Use a specific account](/ai/mcp-server/setup#use-a-specific-account) for setup examples. +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](/ai/mcp-server/setup#select-an-account) for setup examples. Accounts that require mTLS are not available through the public MCP Server. diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index a5e10ddc..9846bbaa 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -1,6 +1,6 @@ --- title: 'Set up the Checkly MCP Server' -description: 'Configure OAuth or API-key authentication for the Checkly MCP Server over Streamable HTTP.' +description: 'Choose an authentication method, connect an MCP client, select an account, and verify the Checkly MCP Server connection.' sidebarTitle: 'Setup' canonical: 'https://www.checklyhq.com/docs/ai/mcp-server/setup/' --- @@ -11,38 +11,62 @@ Use the production MCP endpoint in your client: https://api.checklyhq.com/mcp ``` +## Choose an authentication method + +| Method | Best for | Checkly access | +| --- | --- | --- | +| OAuth (recommended) | Interactive use with a [supported OAuth client](#supported-oauth-clients) | Uses your Checkly user and the permissions granted during sign-in. | +| User API key | Personal clients that cannot use Checkly OAuth but can send custom HTTP headers | Uses your Checkly user and account memberships. User API keys start with `cu_...`. | +| Service API key | Shared or non-interactive clients that need a stable, account-scoped identity | Uses the account and role configured on the key. Service API keys start with `sv_...` and require an Enterprise plan. | + +OAuth avoids storing a long-lived Checkly credential in your MCP client. Use an API key when OAuth is unavailable or when a non-interactive workflow needs an account-scoped service identity. + +## Set up with OAuth + + +Before connecting with OAuth, ensure you have: + +- A Checkly user account. +- Access to the Checkly account you want the MCP client to use. +- A [supported OAuth client](#supported-oauth-clients). + + -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. +The Checkly OAuth flow only supports Checkly-approved clients. Clients that rely on [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) are rejected. -## Supported clients +### Supported OAuth clients -The public Checkly MCP Server currently supports OAuth for these clients: +| Client | Setup | +| --- | --- | +| ChatGPT | [Follow the ChatGPT setup](#chatgpt). | +| Claude Desktop | [Follow the Claude Desktop setup](#claude-desktop). | +| Claude Code | [Add the server from Claude Code](#claude-code). | +| Devin CLI | [Add Checkly's approved OAuth client](#devin-cli). | +| Antigravity | [Add Checkly's approved OAuth client](#antigravity). | +| OpenCode | [Add Checkly's approved OAuth client](#opencode). | +| Cursor | [Configure Cursor's approved OAuth client](#cursor). | +| VS Code | [Add the server to VS Code](#vs-code). | -| Client | Support status | Notes | -| --- | --- | --- | -| ChatGPT | Supported | Use the Checkly MCP endpoint from this page. | -| Claude Desktop | Supported | Use the Checkly MCP endpoint as the remote MCP server URL. | -| Claude Code | Supported | Add the server with the HTTP transport. | -| Devin CLI | Supported | Requires Devin CLI and uses Checkly's static Devin MCP OAuth client. | -| Antigravity | Supported | Use the Checkly MCP endpoint as the MCP server URL. | -| OpenCode | Supported | Uses Checkly's static OpenCode MCP OAuth client with OpenCode's default redirect URI. | -| 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. | +If you want Checkly to support another compatible OAuth client, [share feedback or requests](https://feedback.checklyhq.com). -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. +### Configure your OAuth client -If you want Checkly to support another compatible client, [share feedback or requests](https://feedback.checklyhq.com). + -## ChatGPT +**ChatGPT** -Follow OpenAI's [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) guide. Use the Checkly MCP endpoint from this page as the MCP server endpoint. +Follow OpenAI's [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) guide. Use the Checkly MCP endpoint from this page as the MCP server endpoint. -## Claude Desktop + + +**Claude Desktop** Follow Claude's [custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) guide. Use the Checkly MCP endpoint from this page as the remote MCP server URL. -## Claude Code + + +**Claude Code** Add the server with the HTTP transport: @@ -52,72 +76,51 @@ 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 + - -Before using API-key authentication, ensure you have: +**Devin CLI** -- 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. - +Add the server with Checkly's Devin OAuth client ID: -Use API-key authentication only when OAuth is not practical for your workflow. Send the API key in the `Authorization` header: +```bash Terminal +devin mcp add checkly https://api.checklyhq.com/mcp --transport http --oauth-client-id tpc_5apxvvouctRhwLo7ARsjYA +``` + +Then authenticate: ```bash Terminal -claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "Authorization: Bearer " +devin mcp login checkly --oauth-client-id tpc_5apxvvouctRhwLo7ARsjYA ``` -For clients that use an `mcpServers` JSON configuration, add the header to the Checkly server entry: +Complete the OAuth flow when prompted. -```json mcp.json + + +**Antigravity** + +Add the server to `~/.gemini/config/mcp_config.json` for global use, or `.agents/mcp_config.json` in your workspace: + +```json mcp_config.json { "mcpServers": { "checkly": { - "url": "https://api.checklyhq.com/mcp", - "headers": { - "Authorization": "Bearer " + "serverUrl": "https://api.checklyhq.com/mcp", + "oauth": { + "clientId": "tpc_3qGL89LbJQfbt6peyLEUdE" } } } } ``` -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 +Open **Settings**, select **Customizations**, and authenticate the Checkly server. Follow Google's [Antigravity MCP integration](https://antigravity.google/docs/mcp) guide for the client workflow. -Use this configuration: + -- MCP endpoint: `https://api.checklyhq.com/mcp` -- OAuth client ID: `tpc_5apxvvouctRhwLo7ARsjYA` -- Transport: `http` - -Add the server with the HTTP transport and Checkly's Devin OAuth client ID: - -```bash Terminal -devin mcp add checkly https://api.checklyhq.com/mcp --transport http --oauth-client-id tpc_5apxvvouctRhwLo7ARsjYA -``` - -Then authenticate: - -```bash Terminal -devin mcp login checkly --oauth-client-id tpc_5apxvvouctRhwLo7ARsjYA -``` - -Complete the OAuth flow when prompted. - -## Antigravity - -Follow Google's [Antigravity MCP integration](https://antigravity.google/docs/mcp) guide. Use the Checkly MCP endpoint from this page as the MCP server URL. - -## OpenCode +**OpenCode** -Before configuring OpenCode, ensure you have: - -- OpenCode installed -- Port `19876` available for the OAuth callback +Before configuring OpenCode, ensure port `19876` is available for the OAuth callback. Add the server to your OpenCode configuration: @@ -145,7 +148,9 @@ opencode mcp auth checkly OpenCode must use the redirect URI shown above. If port `19876` is already in use, this static OAuth client will not work with a different local callback port unless Checkly has approved that redirect URI. -## Cursor + + +**Cursor** Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects: @@ -180,7 +185,9 @@ Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` Restart Cursor after changing the configuration. -## VS Code + + +**VS Code** Add the server to `.vscode/mcp.json` in your workspace, or to your VS Code user profile: @@ -197,54 +204,142 @@ Add the server to `.vscode/mcp.json` in your workspace, or to your VS Code user Restart VS Code after changing the configuration. -## Known client limitations +### Known OAuth limitations + +- **Cline:** Cline is not currently supported for Checkly OAuth. You can follow or upvote the [Checkly Cline support request](https://feedback.checklyhq.com/p/support-cline-as-mcp-client). +- **Codex:** Checkly does not currently provide an approved Codex OAuth client. You can [connect Codex with an API key](#codex-with-an-api-key) or follow the [Checkly Codex OAuth support request](https://feedback.checklyhq.com/p/support-codex-for-checkly-mcp). +- **Windsurf / Devin Desktop:** Windsurf / Devin Desktop is not currently supported for Checkly OAuth. You can follow or upvote the [Checkly Devin support request](https://feedback.checklyhq.com/p/support-devin-devin-cli-for-checkly-mcp). + +## Set up with an API key + + +Before connecting with an API key, 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. + + +Send the key as a bearer token in every request: -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). +```text +Authorization: Bearer +``` -### Cline +Deprecated account API keys and old `sk_...` service-key formats are rejected. -Cline is not currently supported for Checkly MCP OAuth because of its current OAuth limitation. You can follow or upvote the [Checkly Cline support request](https://feedback.checklyhq.com/p/support-cline-as-mcp-client). +### Choose an API key -### Codex +| Key | Use it when | Access behavior | +| --- | --- | --- | +| User API key (`cu_...`) | You need a personal fallback for a client that cannot use Checkly OAuth. | Inherits your user access and account memberships. Removing your user from an account removes the key's access to that account. | +| Service API key (`sv_...`) | A shared or non-interactive client needs a stable identity that is not tied to a user. | Limited to one account and the role selected when the key is created. Available on Enterprise plans. | -Codex is not currently supported for Checkly MCP OAuth. Codex does not support CIMD for this flow, and Checkly cannot use a static OAuth client because Codex changes the callback port expected during OAuth. You can follow or upvote the [Checkly Codex support request](https://feedback.checklyhq.com/p/support-codex-for-checkly-mcp). +See [Creating an API key in Checkly](/admin/creating-api-key) for key creation, roles, and revocation. -### Windsurf / Devin Desktop + +API keys are long-lived credentials. Store them in your client's secret storage or an environment variable, and rotate them when they are no longer needed. API-key sessions cannot use the `invite-account-member` tool. + -Windsurf / Devin Desktop is not currently supported for Checkly MCP OAuth because of its current OAuth limitation. You can follow or upvote the [Checkly Devin support request](https://feedback.checklyhq.com/p/support-devin-devin-cli-for-checkly-mcp). +### Configure an API-key client -## Use a specific account + -If you belong to multiple Checkly accounts, tell your MCP client which account you want to use in your prompt: +**Claude Code** -```text title="Prompt" wrap -Use Checkly to show the accounts I can access, then show failing checks for . +Pass the authorization header when you add the server: + +```bash Terminal +claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "Authorization: Bearer " ``` -To make every request from an MCP server configuration use the same account, set the `X-Checkly-Account` header when your client supports custom MCP headers. + -For Claude Code, add the header when you register the server: +**Codex** + +Store the key in an environment variable and tell Codex to use it as the bearer token: ```bash Terminal -claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "X-Checkly-Account: " +export CHECKLY_API_KEY="" +codex mcp add checkly --url https://api.checklyhq.com/mcp --bearer-token-env-var CHECKLY_API_KEY +``` + +Restart Codex from an environment where `CHECKLY_API_KEY` is set. + + + +**OpenCode** + +Store the key in `CHECKLY_API_KEY`, disable automatic OAuth, and reference the environment variable from your OpenCode configuration: + +```json opencode.json +{ + "mcp": { + "checkly": { + "type": "remote", + "url": "https://api.checklyhq.com/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer {env:CHECKLY_API_KEY}" + } + } + } +} ``` -For clients that use an `mcpServers` JSON configuration, add `headers` to the Checkly server entry: + + +**VS Code** + +Use an input variable so the key is not stored in `mcp.json`: ```json mcp.json { - "mcpServers": { + "inputs": [ + { + "type": "promptString", + "id": "checkly-api-key", + "description": "Checkly API key", + "password": true + } + ], + "servers": { "checkly": { + "type": "http", "url": "https://api.checklyhq.com/mcp", "headers": { - "X-Checkly-Account": "" + "Authorization": "Bearer ${input:checkly-api-key}" } } } } ``` -Use the account ID from Checkly. Omit the header when you want to choose the account in your prompts. +## Select an account + +OAuth sessions and user API keys can access each account available to the authenticated user. Service API keys are already limited to the account configured on the key. + +If you can access multiple accounts, tell your MCP client which account you want to use in your prompt: + +```text title="Prompt" wrap +Use Checkly to show the accounts I can access, then show failing checks for . +``` + +To make every request from a connection use the same account, set the `X-Checkly-Account` header when your client supports custom MCP headers: + +```text +X-Checkly-Account: +``` + +For Claude Code, add the header when you register the server: + +```bash Terminal +claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "X-Checkly-Account: " +``` + +For other clients, add the same header to the Checkly server entry using that client's custom-header configuration. + +Use the account ID from Checkly. Omit the header when you want to choose the account in your prompts. You do not need this header with a service API key because the key is already scoped to one account. ## Verify the connection @@ -260,4 +355,4 @@ Then verify tool access: Use Checkly to list the tools available to this session. ``` -The visible tools depend on the 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 and the Checkly role associated with the user or service API key. See [Security and permissions](/ai/mcp-server/security-and-permissions) for details. diff --git a/ai/mcp-server/tools.mdx b/ai/mcp-server/tools.mdx index 9eae1b10..1823277f 100644 --- a/ai/mcp-server/tools.mdx +++ b/ai/mcp-server/tools.mdx @@ -71,6 +71,7 @@ Trigger the checks tagged production-smoke, then poll the test session until res | --- | --- | --- | | `list-test-sessions` | Read | List recent test sessions with filters and cursor ordering. | | `get-test-session` | Read | Return one test session and compact result rows. | +| `list-test-session-results` | Read | List compact result rows for one test session with bounded pagination and optional result filters. | | `get-test-session-result` | Read | Return compact detail for one test-session result, including useful run metadata and small summaries. | Example prompt: diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index 06d2edb3..03dffd04 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -9,49 +9,64 @@ canonical: 'https://www.checklyhq.com/docs/ai/mcp-server/troubleshooting/' Before troubleshooting, confirm: - Your MCP client is configured with `https://api.checklyhq.com/mcp`. -- 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 ` 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. +- 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 fails +## Authentication -If your client reports that authentication is required or invalid: +### OAuth sign-in fails -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 `. -3. Confirm the endpoint is exactly `https://api.checklyhq.com/mcp`. +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](/ai/mcp-server/setup#supported-oauth-clients). +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`. -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. - - -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. - +If the browser login page shows a "Something went wrong" error, contact [Checkly Support](mailto:support@checklyhq.com). Include the MCP client, the Checkly account, and the approximate time of the error. -## OAuth registration fails +### 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 clients list](/ai/mcp-server/setup#supported-clients). Unsupported OAuth clients cannot complete the Checkly OAuth flow, 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 OAuth clients list](/ai/mcp-server/setup#supported-oauth-clients). 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](/ai/mcp-server/setup#set-up-with-an-api-key) 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 `. +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](/ai/mcp-server/setup#set-up-with-an-api-key) for client examples and [Creating an API key in Checkly](/admin/creating-api-key) for key management. -## No tools are listed +## 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 and complete OAuth again, or confirm your API-key header is still configured. +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 +### 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. +- 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. @@ -62,19 +77,29 @@ The `invite-account-member` tool is not available with API-key authentication. R 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 +### 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](/ai/mcp-server/security-and-permissions#role-checks) for the access required by write and run actions. + +## Account selection -If you belong to multiple Checkly accounts, tell your MCP client which account to use in your prompt. +### A tool asks for an account -Ask your client: +OAuth sessions and user API keys can access multiple Checkly accounts. Ask your client: ```text title="Prompt" wrap Use Checkly to show the accounts I can access, then show failing checks for . ``` -To always use the same account, set the `X-Checkly-Account` header in your MCP server configuration. See [Use a specific account](/ai/mcp-server/setup#use-a-specific-account). +To always use the same account, set the `X-Checkly-Account` header in your MCP server configuration. See [Select an account](/ai/mcp-server/setup#select-an-account). -## The MCP server cannot create or deploy check code +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. @@ -86,11 +111,13 @@ Use Checkly to prepare the local check authoring runbook for a browser check. Then run the returned Checkly CLI steps in your local project. -## Write tools did more than expected +## 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](mailto:support@checklyhq.com). Include the MCP client you used, the Checkly account, the tool name, and the approximate time of the action. +If a write tool changed more than you expected, contact [Checkly Support](mailto:support@checklyhq.com). Include the MCP client, the Checkly account, the tool name, and the approximate time of the action. Before approving write tool calls, check: @@ -99,10 +126,12 @@ Before approving write tool calls, check: - Whether subscribers will be notified. - Whether the action consumes check-run or RCA quota. -## Browser clients or web IDEs cannot connect +## 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 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. +1. If you use OAuth, confirm the client is in the [supported OAuth clients list](/ai/mcp-server/setup#supported-oauth-clients). +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.