From 9012c51df12f0f77d31db3620f864077843b72d9 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Fri, 19 Jun 2026 12:04:20 +0200 Subject: [PATCH 01/14] Add MCP server documentation --- ai/mcp-server.mdx | 90 +++++++++++++ ai/mcp-server/security-and-permissions.mdx | 76 +++++++++++ ai/mcp-server/setup.mdx | 146 +++++++++++++++++++++ ai/mcp-server/tools.mdx | 144 ++++++++++++++++++++ ai/mcp-server/troubleshooting.mdx | 103 +++++++++++++++ ai/overview.mdx | 26 ++-- docs.json | 10 ++ 7 files changed, 585 insertions(+), 10 deletions(-) create mode 100644 ai/mcp-server.mdx create mode 100644 ai/mcp-server/security-and-permissions.mdx create mode 100644 ai/mcp-server/setup.mdx create mode 100644 ai/mcp-server/tools.mdx create mode 100644 ai/mcp-server/troubleshooting.mdx diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx new file mode 100644 index 00000000..8067b22d --- /dev/null +++ b/ai/mcp-server.mdx @@ -0,0 +1,90 @@ +--- +title: 'Checkly MCP Server' +description: 'Connect MCP-compatible AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.' +sidebarTitle: 'MCP Server' +--- + +The Checkly MCP Server lets MCP-compatible AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation. + +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. + +Use [Checkly Skills](/ai/skills) and the [Checkly CLI](/cli/overview) when your agent needs to create, edit, test, bundle, or deploy check code. The MCP server runs remotely and cannot access your local filesystem. + +## What you can do + +- Inspect account membership, plan, and feature entitlements. +- Check which checks are passing, failing, muted, or deactivated. +- Read compact check results and test-session results. +- Fetch normalized result asset manifests and bounded text assets. +- Start or read Rocky AI root cause analyses. +- Trigger existing deployed checks on demand. +- Manage account-level environment variables and secrets. +- Read status pages and manage status page incidents. + +## Quick start + + +Before connecting an MCP client, ensure you have: + +- A Checkly user account. +- Access to the Checkly account you want the MCP client to use. +- An MCP-compatible client that supports Streamable HTTP and OAuth. +- The Checkly MCP endpoint: `https://api.checklyhq.com/mcp`. + + +Add the Checkly MCP endpoint to your client, complete the OAuth flow, then ask your client to verify the connection: + +```text +Use Checkly to show who I am and which accounts I can access. +``` + +If you belong to more than one Checkly account, set the account in your client configuration with the `X-Checkly-Account` header when your client supports headers, or pass `accountId` in tool calls. + +See [Set up the MCP server](/ai/mcp-server/setup) for client configuration examples. + +## Example prompts + +Basic prompts: + +```text +Show me the current status of my Checkly checks. +``` + +```text +List open status page incidents. +``` + +```text +What features are available on my current Checkly plan? +``` + +Advanced prompts: + +```text +Investigate the latest failed result for the checkout API check. If there is an error group, check whether an RCA already exists before triggering a new one. +``` + +```text +Trigger the checks tagged production-smoke, then follow the test session until results are available. +``` + +```text +Create a major status page incident for the API outage, but do not notify subscribers until I confirm the message. +``` + +## MCP vs Skills + +| Use case | Recommended path | +| --- | --- | +| Read live Checkly account data | MCP Server | +| Trigger existing deployed checks | MCP Server | +| Create or edit check code | [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview) | +| Test or deploy local Monitoring as Code projects | [Checkly CLI](/cli/overview) | +| Add reusable Checkly best practices to an agent | [Checkly Skills](/ai/skills) | + +## Learn more + +- [Set up the MCP server](/ai/mcp-server/setup) +- [MCP tools reference](/ai/mcp-server/tools) +- [Security and permissions](/ai/mcp-server/security-and-permissions) +- [Troubleshooting](/ai/mcp-server/troubleshooting) diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx new file mode 100644 index 00000000..f3576d01 --- /dev/null +++ b/ai/mcp-server/security-and-permissions.mdx @@ -0,0 +1,76 @@ +--- +title: 'MCP security and permissions' +description: 'Understand how the Checkly MCP Server authenticates users, filters tools by scope, resolves account context, and handles write actions.' +sidebarTitle: 'Security & permissions' +--- + +The Checkly MCP Server uses OAuth and Checkly account authorization together. OAuth scopes 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. + +Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. + +## Tool scopes + +| Scope | Allows | +| --- | --- | +| `checkly:account:read` | Account identity, entitlements, members, and local CLI handoff runbooks. | +| `checkly:account:invite` | Account member invites. | +| `checkly:checks:read` | Check status, check results, and performance summaries. | +| `checkly:checks:run` | On-demand runs for existing deployed checks. | +| `checkly:test-sessions:read` | Test sessions and test-session result summaries. | +| `checkly:assets:read` | Result asset manifests and selected asset fetches. | +| `checkly:rca:read` | Error groups and existing root cause analyses. | +| `checkly:rca:run` | New root cause analysis runs. | +| `checkly:environment-variables:read` | Account-level environment variable metadata. | +| `checkly:environment-variables:write` | Create and update account-level variables and secrets. | +| `checkly:status-pages:read` | Status pages, cards, and services. | +| `checkly:incidents:read` | Status page incidents. | +| `checkly:incidents:write` | Create, update, and resolve status page incidents. | + +Tools are filtered from `tools/list` when the MCP session does not include the required scope. Tool calls are also rejected if the session lacks the required scope. + +## Account resolution + +Most tools operate on one Checkly account. Checkly resolves the account in this order: + +1. `accountId` in the tool arguments. +2. `X-Checkly-Account` on the MCP connection. +3. Your sole account, if your user belongs to exactly one account. + +If you belong to multiple accounts and no account can be resolved, the tool returns a message with the accounts available to your session. + +Accounts that require mTLS are not available through the MCP Server. + +## Role checks + +Some tools require both an OAuth scope 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. diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx new file mode 100644 index 00000000..e7d6b6a0 --- /dev/null +++ b/ai/mcp-server/setup.mdx @@ -0,0 +1,146 @@ +--- +title: 'Set up the Checkly MCP Server' +description: 'Configure an MCP-compatible client to connect to the Checkly MCP Server over Streamable HTTP.' +sidebarTitle: 'Set up' +--- + + +Before setting up the Checkly MCP Server, ensure you have: + +- A Checkly user account. +- Access to the Checkly account you want your MCP client to use. +- An MCP-compatible client that supports Streamable HTTP and OAuth. +- The Checkly MCP endpoint: `https://api.checklyhq.com/mcp`. + + +The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives a token scoped to the Checkly tools it can use. + +## Endpoint + +Use the production MCP endpoint: + +```text +https://api.checklyhq.com/mcp +``` + +The server exposes protected-resource metadata for OAuth discovery. Most MCP clients discover this automatically when they connect to the endpoint. + +## Codex + +Add the server: + +```bash Terminal +codex mcp add checkly --url https://api.checklyhq.com/mcp +``` + +Then log in: + +```bash Terminal +codex mcp login checkly +``` + +Restart Codex after adding the server. + +## Claude Code + +Add the server with the HTTP transport: + +```bash Terminal +claude mcp add --transport http checkly https://api.checklyhq.com/mcp +``` + +Start a Claude Code session and complete the OAuth flow when prompted. + +## Cursor + +Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects: + +```json mcp.json +{ + "mcpServers": { + "checkly": { + "url": "https://api.checklyhq.com/mcp" + } + } +} +``` + +Restart Cursor after changing the configuration. + +## VS Code + +Add the server to `.vscode/mcp.json` in your workspace, or to your VS Code user profile: + +```json mcp.json +{ + "servers": { + "checkly": { + "type": "http", + "url": "https://api.checklyhq.com/mcp" + } + } +} +``` + +Restart VS Code after changing the configuration. + +## Other MCP clients + +For clients that accept a generic `mcpServers` configuration, use: + +```json mcp.json +{ + "mcpServers": { + "checkly": { + "url": "https://api.checklyhq.com/mcp", + "headers": { + "X-Checkly-Account": "" + } + } + } +} +``` + +Omit `headers` if you want Checkly to resolve the account from tool arguments or your user membership. + +## Choose an account + +Most tools need an account context. Checkly resolves the account in this order: + +1. The `accountId` argument passed to the tool. +2. The `X-Checkly-Account` header on the MCP connection. +3. Your sole account, if your user belongs to exactly one account. + +If you belong to multiple accounts and do not provide an account, the tool returns a message with the accounts you can access. + +## Verify the connection + +After authentication, ask your MCP client: + +```text +Use Checkly to show who I am and which accounts I can access. +``` + +Then verify tool access: + +```text +Use Checkly to list the tools available to this session. +``` + +The visible tools depend on the OAuth scopes granted to your MCP session. See [Security and permissions](/ai/mcp-server/security-and-permissions) for the scope list. + +## Test with MCP Inspector + +Use MCP Inspector when you need to debug the connection outside your regular client. + +```bash Terminal +npx @modelcontextprotocol/inspector +``` + +In the Inspector UI: + +1. Select Streamable HTTP. +2. Enter `https://api.checklyhq.com/mcp`. +3. Connect and complete the OAuth flow. +4. Call `whoami`. +5. Open Tools and confirm the expected tools are listed. diff --git a/ai/mcp-server/tools.mdx b/ai/mcp-server/tools.mdx new file mode 100644 index 00000000..9d5beefa --- /dev/null +++ b/ai/mcp-server/tools.mdx @@ -0,0 +1,144 @@ +--- +title: 'Checkly MCP tools' +description: 'Reference for the tools exposed by the Checkly MCP Server, grouped by workflow and required OAuth scope.' +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 scope. Some write tools also require a matching Checkly account role, such as Admin or Read & Write. + +## Account tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `whoami` | `checkly:account:read` | Read | Return the authenticated user and account memberships visible to the MCP session. | +| `get-account-entitlements` | `checkly:account:read` | Read | Return the resolved account plan and feature entitlement state. | +| `list-account-members` | `checkly:account:read` | Read | List account members and pending invites. | +| `invite-account-member` | `checkly:account:invite` | Write | Invite a user to the resolved account. Requires Owner or Admin access, sends an invite email, and is not idempotent. | +| `prepare-local-check-authoring` | `checkly:account:read` | Read | Return an account-aware runbook for creating, testing, and deploying check code with the local Checkly CLI. | + +Example prompts: + +```text +Use Checkly to show who I am and which accounts I can access. +``` + +```text +Prepare the local Checkly CLI steps to create a browser check for checkout. +``` + +## Check tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `get-check-status` | `checkly:checks:read` | Read | Return current status for checks in the account, including check type, activation state, and passing or failing state. | +| `list-check-results` | `checkly:checks:read` | Read | List recent compact results for one check. Raw logs, traces, screenshots, videos, and download URLs are omitted. | +| `get-check-result` | `checkly:checks:read` | Read | Return compact detail for one check result. | +| `get-check-performance-summary` | `checkly:checks:read` | Read | Return average, P50, P95, and P99 response-time metrics for one check over a date range when data is available. | +| `trigger-checks` | `checkly:checks:run` | Write | Run existing deployed checks on demand and record the run as a test session. Consumes check-run execution quota. | + +`trigger-checks` only runs checks that already exist on the account. Use `prepare-local-check-authoring` and the Checkly CLI when you need to create, test, or deploy local check code. + +Example prompts: + +```text +Show me failing checks and summarize what changed in their latest results. +``` + +```text +Trigger the checks tagged production-smoke, then poll the test session until results are available. +``` + +## Test session tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `list-test-sessions` | `checkly:test-sessions:read` | Read | List recent test sessions with filters and cursor ordering. | +| `get-test-session` | `checkly:test-sessions:read` | Read | Return one test session and compact result rows. | +| `get-test-session-result` | `checkly:test-sessions:read` | Read | Return compact detail for one test-session result, including useful run metadata and small summaries. | + +Example prompt: + +```text +Find the latest failed test session and show me the failed result IDs. +``` + +## Result asset tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `list-check-result-assets` | `checkly:checks:read`, `checkly:assets:read` | Read | Return a normalized asset manifest for a check result. | +| `fetch-check-result-asset` | `checkly:checks:read`, `checkly:assets:read` | Read | Fetch one selected check-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | +| `list-test-session-result-assets` | `checkly:test-sessions:read`, `checkly:assets:read` | Read | Return a normalized asset manifest for a test-session result. | +| `fetch-test-session-result-asset` | `checkly:test-sessions:read`, `checkly:assets:read` | Read | Fetch one selected test-session-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | + +Example prompt: + +```text +For the failed check result, list available assets and fetch the text log if one exists. +``` + +## Root cause analysis tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `get-error-group-root-cause-analyses` | `checkly:rca:read` | Read | Return a check or test-session error group and any existing root cause analyses. | +| `get-root-cause-analysis` | `checkly:rca:read` | Read | Return one root cause analysis by RCA ID. Pending analyses return compact polling status. | +| `trigger-root-cause-analysis` | `checkly:rca:run` | Write | Trigger a new RCA for a check or test-session error group. Requires run access and consumes RCA invocation quota. | + +Call `get-error-group-root-cause-analyses` before triggering a new RCA so your agent can reuse existing analysis when available. + +Example prompt: + +```text +Check whether this error group already has an RCA. If it does not, ask me before triggering a new one. +``` + +## Environment variable tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `list-account-environment-variables` | `checkly:environment-variables:read` | Read | List account-level variables and secrets. Secret values are returned as `null`. | +| `get-account-environment-variable` | `checkly:environment-variables:read` | Read | Get one account-level variable by key. Secret values are returned as `null`. | +| `create-account-environment-variable` | `checkly:environment-variables:write` | Write | Create an account-level variable or secret. Secret values are encrypted and not echoed back. | +| `update-account-environment-variable` | `checkly:environment-variables:write` | Write | Update an account-level variable or secret by key. To update a secret, pass `secret: true`. | + +Example prompt: + +```text +List account environment variables and tell me whether API_TOKEN is stored as a secret. +``` + +## Status page tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `list-status-pages` | `checkly:status-pages:read` | Read | List status pages, including cards and services needed for incident targeting. | +| `get-status-page` | `checkly:status-pages:read` | Read | Get one status page with cards and services. | + +Example prompt: + +```text +List my status pages and show the service IDs for the production page. +``` + +## Incident tools + +| Tool | Scope | Type | Description | +| --- | --- | --- | --- | +| `list-status-page-incidents` | `checkly:incidents:read` | Read | List status page incidents, optionally filtered by page and incident status. | +| `get-status-page-incident` | `checkly:incidents:read` | Read | Get one status page incident with services and incident updates. | +| `create-status-page-incident` | `checkly:incidents:write`, `checkly:status-pages:read` | Write | Create a new status page incident and optionally notify subscribers. Not idempotent. | +| `update-status-page-incident` | `checkly:incidents:write` | Write | Post a progress update to an existing incident and optionally notify subscribers. Not idempotent. | +| `resolve-status-page-incident` | `checkly:incidents:write` | Write | Resolve an incident by posting a final resolved update and optionally notifying subscribers. Not idempotent. | + +Example prompts: + +```text +Show open status page incidents and summarize their latest updates. +``` + +```text +Draft a major status page incident for the API outage and wait for confirmation before notifying subscribers. +``` diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx new file mode 100644 index 00000000..75f91163 --- /dev/null +++ b/ai/mcp-server/troubleshooting.mdx @@ -0,0 +1,103 @@ +--- +title: 'Troubleshoot the Checkly MCP Server' +description: 'Resolve common Checkly MCP Server setup, authentication, account selection, and tool access issues.' +sidebarTitle: 'Troubleshooting' +--- + + +Before troubleshooting, confirm: + +- Your MCP client is configured with `https://api.checklyhq.com/mcp`. +- You completed the OAuth login flow. +- You restarted your MCP client after editing configuration. +- Your Checkly user has access to the account you want to use. + + +## Authentication fails + +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`. + +For Codex, run: + +```bash Terminal +codex mcp login checkly +``` + +## No tools are listed + +Visible tools depend on the OAuth scopes granted to the MCP session. If no tools appear, reconnect and complete OAuth again. + +Use this prompt to verify identity and account access: + +```text +Use Checkly to show who I am and which accounts I can access. +``` + +If `whoami` is unavailable, the session does not have `checkly:account:read`. + +## A specific tool is missing + +Each tool requires a scope. For example: + +- Check status and results require `checkly:checks:read`. +- Test sessions require `checkly:test-sessions:read`. +- Asset tools require `checkly:assets:read` plus the related result scope. +- Incident write tools require `checkly:incidents:write`. + +See [MCP tools](/ai/mcp-server/tools) for the full scope list. + +## The tool asks for an account + +If you belong to multiple Checkly accounts, pass `accountId` in the tool call or configure the `X-Checkly-Account` header when your client supports headers. + +Ask your client: + +```text +Use Checkly to show the accounts I can access, then use accountId for the next Checkly request. +``` + +## 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: + +```text +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 + +Some write tools are not idempotent. Retrying a call can create another invite, another incident, or another incident update. + +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 clients or web IDEs 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. Try a command-line client such as Codex or Claude Code. +2. Test the endpoint with MCP Inspector. +3. Confirm the client supports Streamable HTTP MCP servers with OAuth. + +## MCP Inspector cannot connect + +Use Streamable HTTP, not SSE or stdio, and enter: + +```text +https://api.checklyhq.com/mcp +``` + +Complete OAuth in the browser window opened by Inspector, then call `whoami`. diff --git a/ai/overview.mdx b/ai/overview.mdx index bc4f0455..f98c26b5 100644 --- a/ai/overview.mdx +++ b/ai/overview.mdx @@ -1,6 +1,6 @@ --- title: 'AI Agents & Coding Assistants' -description: 'Use AI agents and coding assistants to create, update, and deploy your Checkly monitoring setup with skills and rules.' +description: 'Use AI agents and coding assistants with Checkly Skills, rules, and the Checkly MCP Server.' sidebarTitle: 'Agents & Checkly' keywords: ['mcp', 'ai', 'rules', 'generate checks', 'agents', 'context'] --- @@ -44,35 +44,41 @@ Provide the necessary Checkly context and let your AI agent of choice do the res ## Add Checkly context to your AI agent conversation -Install [Checkly Skills](/ai/skills) or add the [Checkly Rules](/ai/rules) to your AI conversation to give your AI agent enough context to perform Checkly-related tasks. +Install [Checkly Skills](/ai/skills), add [Checkly Rules](/ai/rules), or connect the [Checkly MCP Server](/ai/mcp-server) to give your AI agent enough context to perform Checkly-related tasks. - + Let your agents pull in all required Checkly context on demand. + +Give your agents live access to Checkly account data and remote actions. + + Include the entire Checkly context in commands or documentation. -### Skills vs Rules +### Skills, MCP, and Rules **Use Skills** when your AI agent supports the [Agent Skills](https://agentskills.io) standard. Skills load context on demand, keeping your agent's context window lean until Checkly-related tasks arise. This is the recommended approach for compatible agents. +**Use the MCP Server** when your agent needs live Checkly data or remote account actions, such as reading check status, inspecting test sessions, triggering existing checks, reading RCA, or managing status page incidents. + **Use Rules** when your agent doesn't support skills or when you want the Checkly context always available. Rules files are loaded at session start and provide consistent context throughout your conversation. -## Why is there no Checkly MCP server (yet)? +## When to use the Checkly MCP Server The MCP concept is often used to enable LLMs to interact with external systems. It acts as a bridge between the AI model and the target system, translating natural language commands into actionable API calls or code snippets. -**With Monitoring as Code and agent-friendly CLI commands, Checkly already provides a native way to control your monitoring infrastructure via code and access monitoring results via the command line.** +The [Checkly MCP Server](/ai/mcp-server) connects MCP-compatible clients to Checkly over Streamable HTTP. It exposes tools for account context, check status and results, test sessions, result assets, root cause analyses, environment variables, status pages, incidents, and triggering existing checks. -Whether you need to configure your monitoring setup, access check data or declare incidents, AI can write and update the necessary construct files and execute the Checkly CLI commands autonomously. +**Use the MCP Server for live Checkly account operations. Use Skills and the Checkly CLI for Monitoring as Code authoring.** -We are researching additional AI-native workflows. [Let us know in the public roadmap](https://feedback.checklyhq.com/p/checkly-mcp) if you are interested in more agent-friendly integrations. +The MCP server runs remotely and cannot access your local filesystem. When you need to create, edit, test, or deploy check code, use [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview). ## Markdown access @@ -131,7 +137,7 @@ Based on this, how do I set up a browser check with a custom user agent? ``` -## LLMs.txt +## LLMs.txt The [llms.txt standard](https://llmstxt.org/) provides a machine-readable index of all available documentation pages. Checkly publishes an `llms.txt` file at [`checklyhq.com/llms.txt`](https://www.checklyhq.com/llms.txt) that lists every documentation page with its markdown URL and a short description. @@ -162,4 +168,4 @@ curl https://www.checklyhq.com/llms.txt # Fetch a specific page from the index curl https://checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/overview.md -``` \ No newline at end of file +``` diff --git a/docs.json b/docs.json index 8e42572b..b76090ba 100644 --- a/docs.json +++ b/docs.json @@ -350,6 +350,16 @@ "pages": [ "ai/rocky-ai", "ai/overview", + { + "group": "MCP Server", + "pages": [ + "ai/mcp-server", + "ai/mcp-server/setup", + "ai/mcp-server/tools", + "ai/mcp-server/security-and-permissions", + "ai/mcp-server/troubleshooting" + ] + }, "ai/skills", "ai/rules" ] From 1674539f5e0c7314310592440c8ee3ce4b660794 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Fri, 19 Jun 2026 12:30:36 +0200 Subject: [PATCH 02/14] Refine MCP server docs --- ai/mcp-server.mdx | 20 ++-- ai/mcp-server/security-and-permissions.mdx | 40 +++---- ai/mcp-server/setup.mdx | 26 +---- ai/mcp-server/tools.mdx | 122 ++++++++++----------- ai/mcp-server/troubleshooting.mdx | 41 +++---- 5 files changed, 111 insertions(+), 138 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 8067b22d..b7eecf95 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -1,14 +1,16 @@ --- title: 'Checkly MCP Server' description: 'Connect MCP-compatible AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.' -sidebarTitle: 'MCP Server' +sidebarTitle: 'Overview' --- The Checkly MCP Server lets MCP-compatible AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation. 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. + Use [Checkly Skills](/ai/skills) and the [Checkly CLI](/cli/overview) when your agent needs to create, edit, test, bundle, or deploy check code. The MCP server runs remotely and cannot access your local filesystem. + ## What you can do @@ -34,8 +36,8 @@ Before connecting an MCP client, ensure you have: Add the Checkly MCP endpoint to your client, complete the OAuth flow, then ask your client to verify the connection: -```text -Use Checkly to show who I am and which accounts I can access. +```text title="Prompt" wrap +Use Checkly to show which accounts I can access. ``` If you belong to more than one Checkly account, set the account in your client configuration with the `X-Checkly-Account` header when your client supports headers, or pass `accountId` in tool calls. @@ -46,29 +48,29 @@ See [Set up the MCP server](/ai/mcp-server/setup) for client configuration examp Basic prompts: -```text +```text title="Prompt" wrap Show me the current status of my Checkly checks. ``` -```text +```text title="Prompt" wrap List open status page incidents. ``` -```text +```text title="Prompt" wrap What features are available on my current Checkly plan? ``` Advanced prompts: -```text +```text title="Prompt" wrap Investigate the latest failed result for the checkout API check. If there is an error group, check whether an RCA already exists before triggering a new one. ``` -```text +```text title="Prompt" wrap Trigger the checks tagged production-smoke, then follow the test session until results are available. ``` -```text +```text title="Prompt" wrap Create a major status page incident for the API outage, but do not notify subscribers until I confirm the message. ``` diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index f3576d01..fa145d50 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -1,10 +1,10 @@ --- title: 'MCP security and permissions' -description: 'Understand how the Checkly MCP Server authenticates users, filters tools by scope, resolves account context, and handles write actions.' +description: 'Understand how the Checkly MCP Server authenticates users, filters tools by permission, resolves account context, and handles write actions.' sidebarTitle: 'Security & permissions' --- -The Checkly MCP Server uses OAuth and Checkly account authorization together. OAuth scopes 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 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. ## Authentication @@ -12,25 +12,25 @@ The MCP Server accepts Auth0-issued bearer tokens for `https://api.checklyhq.com Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. -## Tool scopes +## OAuth permissions -| Scope | Allows | +| Permission | Description | | --- | --- | -| `checkly:account:read` | Account identity, entitlements, members, and local CLI handoff runbooks. | -| `checkly:account:invite` | Account member invites. | -| `checkly:checks:read` | Check status, check results, and performance summaries. | -| `checkly:checks:run` | On-demand runs for existing deployed checks. | -| `checkly:test-sessions:read` | Test sessions and test-session result summaries. | -| `checkly:assets:read` | Result asset manifests and selected asset fetches. | -| `checkly:rca:read` | Error groups and existing root cause analyses. | -| `checkly:rca:run` | New root cause analysis runs. | -| `checkly:environment-variables:read` | Account-level environment variable metadata. | -| `checkly:environment-variables:write` | Create and update account-level variables and secrets. | -| `checkly:status-pages:read` | Status pages, cards, and services. | -| `checkly:incidents:read` | Status page incidents. | -| `checkly:incidents:write` | Create, update, and resolve status page incidents. | - -Tools are filtered from `tools/list` when the MCP session does not include the required scope. Tool calls are also rejected if the session lacks the required scope. +| `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 | + +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 resolution @@ -46,7 +46,7 @@ Accounts that require mTLS are not available through the MCP Server. ## Role checks -Some tools require both an OAuth scope and a Checkly account role: +Some tools require both an OAuth permission and a Checkly account role: | Tool or action | Additional account access required | | --- | --- | diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index e7d6b6a0..51edcb0f 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -13,7 +13,7 @@ Before setting up the Checkly MCP Server, ensure you have: - The Checkly MCP endpoint: `https://api.checklyhq.com/mcp`. -The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives a token scoped to the Checkly tools it can use. +The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives access to the Checkly tools it can use. ## Endpoint @@ -117,30 +117,14 @@ If you belong to multiple accounts and do not provide an account, the tool retur After authentication, ask your MCP client: -```text -Use Checkly to show who I am and which accounts I can access. +```text title="Prompt" wrap +Use Checkly to show which accounts I can access. ``` Then verify tool access: -```text +```text title="Prompt" wrap Use Checkly to list the tools available to this session. ``` -The visible tools depend on the OAuth scopes granted to your MCP session. See [Security and permissions](/ai/mcp-server/security-and-permissions) for the scope list. - -## Test with MCP Inspector - -Use MCP Inspector when you need to debug the connection outside your regular client. - -```bash Terminal -npx @modelcontextprotocol/inspector -``` - -In the Inspector UI: - -1. Select Streamable HTTP. -2. Enter `https://api.checklyhq.com/mcp`. -3. Connect and complete the OAuth flow. -4. Call `whoami`. -5. Open Tools and confirm the expected tools are listed. +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. diff --git a/ai/mcp-server/tools.mdx b/ai/mcp-server/tools.mdx index 9d5beefa..819652e8 100644 --- a/ai/mcp-server/tools.mdx +++ b/ai/mcp-server/tools.mdx @@ -1,144 +1,144 @@ --- title: 'Checkly MCP tools' -description: 'Reference for the tools exposed by the Checkly MCP Server, grouped by workflow and required OAuth scope.' +description: 'Reference for the tools exposed by the Checkly MCP Server, grouped by workflow.' 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 scope. 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 OAuth permission. Some write tools also require a matching Checkly account role, such as Admin or Read & Write. ## Account tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `whoami` | `checkly:account:read` | Read | Return the authenticated user and account memberships visible to the MCP session. | -| `get-account-entitlements` | `checkly:account:read` | Read | Return the resolved account plan and feature entitlement state. | -| `list-account-members` | `checkly:account:read` | Read | List account members and pending invites. | -| `invite-account-member` | `checkly:account:invite` | Write | Invite a user to the resolved account. Requires Owner or Admin access, sends an invite email, and is not idempotent. | -| `prepare-local-check-authoring` | `checkly:account:read` | Read | Return an account-aware runbook for creating, testing, and deploying check code with the local Checkly CLI. | +| Tool | Type | Description | +| --- | --- | --- | +| `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. | +| `prepare-local-check-authoring` | Read | Return an account-aware runbook for creating, testing, and deploying check code with the local Checkly CLI. | Example prompts: -```text -Use Checkly to show who I am and which accounts I can access. +```text title="Prompt" wrap +Use Checkly to show which accounts I can access. ``` -```text +```text title="Prompt" wrap Prepare the local Checkly CLI steps to create a browser check for checkout. ``` ## Check tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `get-check-status` | `checkly:checks:read` | Read | Return current status for checks in the account, including check type, activation state, and passing or failing state. | -| `list-check-results` | `checkly:checks:read` | Read | List recent compact results for one check. Raw logs, traces, screenshots, videos, and download URLs are omitted. | -| `get-check-result` | `checkly:checks:read` | Read | Return compact detail for one check result. | -| `get-check-performance-summary` | `checkly:checks:read` | Read | Return average, P50, P95, and P99 response-time metrics for one check over a date range when data is available. | -| `trigger-checks` | `checkly:checks:run` | Write | Run existing deployed checks on demand and record the run as a test session. Consumes check-run execution quota. | +| Tool | Type | Description | +| --- | --- | --- | +| `get-check-status` | Read | Return current status for checks in the account, including check type, activation state, and passing or failing state. | +| `list-check-results` | Read | List recent compact results for one check. Raw logs, traces, screenshots, videos, and download URLs are omitted. | +| `get-check-result` | Read | Return compact detail for one check result. | +| `get-check-performance-summary` | Read | Return average, P50, P95, and P99 response-time metrics for one check over a date range when data is available. | +| `trigger-checks` | Write | Run existing deployed checks on demand and record the run as a test session. Consumes check-run execution quota. | `trigger-checks` only runs checks that already exist on the account. Use `prepare-local-check-authoring` and the Checkly CLI when you need to create, test, or deploy local check code. Example prompts: -```text +```text title="Prompt" wrap Show me failing checks and summarize what changed in their latest results. ``` -```text +```text title="Prompt" wrap Trigger the checks tagged production-smoke, then poll the test session until results are available. ``` ## Test session tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `list-test-sessions` | `checkly:test-sessions:read` | Read | List recent test sessions with filters and cursor ordering. | -| `get-test-session` | `checkly:test-sessions:read` | Read | Return one test session and compact result rows. | -| `get-test-session-result` | `checkly:test-sessions:read` | Read | Return compact detail for one test-session result, including useful run metadata and small summaries. | +| Tool | Type | Description | +| --- | --- | --- | +| `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. | +| `get-test-session-result` | Read | Return compact detail for one test-session result, including useful run metadata and small summaries. | Example prompt: -```text +```text title="Prompt" wrap Find the latest failed test session and show me the failed result IDs. ``` ## Result asset tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `list-check-result-assets` | `checkly:checks:read`, `checkly:assets:read` | Read | Return a normalized asset manifest for a check result. | -| `fetch-check-result-asset` | `checkly:checks:read`, `checkly:assets:read` | Read | Fetch one selected check-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | -| `list-test-session-result-assets` | `checkly:test-sessions:read`, `checkly:assets:read` | Read | Return a normalized asset manifest for a test-session result. | -| `fetch-test-session-result-asset` | `checkly:test-sessions:read`, `checkly:assets:read` | Read | Fetch one selected test-session-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | +| Tool | Type | Description | +| --- | --- | --- | +| `list-check-result-assets` | Read | Return a normalized asset manifest for a check result. | +| `fetch-check-result-asset` | Read | Fetch one selected check-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | +| `list-test-session-result-assets` | Read | Return a normalized asset manifest for a test-session result. | +| `fetch-test-session-result-asset` | Read | Fetch one selected test-session-result asset. Text assets may be returned inline with a byte limit; binary or large assets return a download link. | Example prompt: -```text +```text title="Prompt" wrap For the failed check result, list available assets and fetch the text log if one exists. ``` ## Root cause analysis tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `get-error-group-root-cause-analyses` | `checkly:rca:read` | Read | Return a check or test-session error group and any existing root cause analyses. | -| `get-root-cause-analysis` | `checkly:rca:read` | Read | Return one root cause analysis by RCA ID. Pending analyses return compact polling status. | -| `trigger-root-cause-analysis` | `checkly:rca:run` | Write | Trigger a new RCA for a check or test-session error group. Requires run access and consumes RCA invocation quota. | +| Tool | Type | Description | +| --- | --- | --- | +| `get-error-group-root-cause-analyses` | Read | Return a check or test-session error group and any existing root cause analyses. | +| `get-root-cause-analysis` | Read | Return one root cause analysis by RCA ID. Pending analyses return compact polling status. | +| `trigger-root-cause-analysis` | Write | Trigger a new RCA for a check or test-session error group. Requires run access and consumes RCA invocation quota. | Call `get-error-group-root-cause-analyses` before triggering a new RCA so your agent can reuse existing analysis when available. Example prompt: -```text +```text title="Prompt" wrap Check whether this error group already has an RCA. If it does not, ask me before triggering a new one. ``` ## Environment variable tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `list-account-environment-variables` | `checkly:environment-variables:read` | Read | List account-level variables and secrets. Secret values are returned as `null`. | -| `get-account-environment-variable` | `checkly:environment-variables:read` | Read | Get one account-level variable by key. Secret values are returned as `null`. | -| `create-account-environment-variable` | `checkly:environment-variables:write` | Write | Create an account-level variable or secret. Secret values are encrypted and not echoed back. | -| `update-account-environment-variable` | `checkly:environment-variables:write` | Write | Update an account-level variable or secret by key. To update a secret, pass `secret: true`. | +| Tool | Type | Description | +| --- | --- | --- | +| `list-account-environment-variables` | Read | List account-level variables and secrets. Secret values are returned as `null`. | +| `get-account-environment-variable` | Read | Get one account-level variable by key. Secret values are returned as `null`. | +| `create-account-environment-variable` | Write | Create an account-level variable or secret. Secret values are encrypted and not echoed back. | +| `update-account-environment-variable` | Write | Update an account-level variable or secret by key. To update a secret, pass `secret: true`. | Example prompt: -```text +```text title="Prompt" wrap List account environment variables and tell me whether API_TOKEN is stored as a secret. ``` ## Status page tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `list-status-pages` | `checkly:status-pages:read` | Read | List status pages, including cards and services needed for incident targeting. | -| `get-status-page` | `checkly:status-pages:read` | Read | Get one status page with cards and services. | +| Tool | Type | Description | +| --- | --- | --- | +| `list-status-pages` | Read | List status pages, including cards and services needed for incident targeting. | +| `get-status-page` | Read | Get one status page with cards and services. | Example prompt: -```text +```text title="Prompt" wrap List my status pages and show the service IDs for the production page. ``` ## Incident tools -| Tool | Scope | Type | Description | -| --- | --- | --- | --- | -| `list-status-page-incidents` | `checkly:incidents:read` | Read | List status page incidents, optionally filtered by page and incident status. | -| `get-status-page-incident` | `checkly:incidents:read` | Read | Get one status page incident with services and incident updates. | -| `create-status-page-incident` | `checkly:incidents:write`, `checkly:status-pages:read` | Write | Create a new status page incident and optionally notify subscribers. Not idempotent. | -| `update-status-page-incident` | `checkly:incidents:write` | Write | Post a progress update to an existing incident and optionally notify subscribers. Not idempotent. | -| `resolve-status-page-incident` | `checkly:incidents:write` | Write | Resolve an incident by posting a final resolved update and optionally notifying subscribers. Not idempotent. | +| Tool | Type | Description | +| --- | --- | --- | +| `list-status-page-incidents` | Read | List status page incidents, optionally filtered by page and incident status. | +| `get-status-page-incident` | Read | Get one status page incident with services and incident updates. | +| `create-status-page-incident` | Write | Create a new status page incident and optionally notify subscribers. Not idempotent. | +| `update-status-page-incident` | Write | Post a progress update to an existing incident and optionally notify subscribers. Not idempotent. | +| `resolve-status-page-incident` | Write | Resolve an incident by posting a final resolved update and optionally notifying subscribers. Not idempotent. | Example prompts: -```text +```text title="Prompt" wrap Show open status page incidents and summarize their latest updates. ``` -```text +```text title="Prompt" wrap Draft a major status page incident for the API outage and wait for confirmation before notifying subscribers. ``` diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index 75f91163..3a8f6500 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -30,26 +30,24 @@ codex mcp login checkly ## No tools are listed -Visible tools depend on the OAuth scopes granted to the MCP session. If no tools appear, reconnect and complete OAuth again. +Visible tools depend on the OAuth permissions granted to the MCP session. If no tools appear: -Use this prompt to verify identity and account access: +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. -```text -Use Checkly to show who I am and which accounts I can access. -``` - -If `whoami` is unavailable, the session does not have `checkly:account:read`. +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 a scope. For example: +Each tool requires an OAuth permission. For example: -- Check status and results require `checkly:checks:read`. -- Test sessions require `checkly:test-sessions:read`. -- Asset tools require `checkly:assets:read` plus the related result scope. -- Incident write tools require `checkly:incidents:write`. +- 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](/ai/mcp-server/tools) for the full scope list. +See [MCP tools](/ai/mcp-server/tools) for the full tool list. ## The tool asks for an account @@ -57,7 +55,7 @@ If you belong to multiple Checkly accounts, pass `accountId` in the tool call or Ask your client: -```text +```text title="Prompt" wrap Use Checkly to show the accounts I can access, then use accountId for the next Checkly request. ``` @@ -67,7 +65,7 @@ The MCP server runs remotely and cannot access your local project files. It cann Ask for a CLI handoff instead: -```text +```text title="Prompt" wrap Use Checkly to prepare the local check authoring runbook for a browser check. ``` @@ -89,15 +87,4 @@ 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. Try a command-line client such as Codex or Claude Code. -2. Test the endpoint with MCP Inspector. -3. Confirm the client supports Streamable HTTP MCP servers with OAuth. - -## MCP Inspector cannot connect - -Use Streamable HTTP, not SSE or stdio, and enter: - -```text -https://api.checklyhq.com/mcp -``` - -Complete OAuth in the browser window opened by Inspector, then call `whoami`. +2. Confirm the client supports Streamable HTTP MCP servers with OAuth. From 47d322a3939b9b5a590d99a8dce5d59fa314dda6 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Fri, 19 Jun 2026 14:33:17 +0200 Subject: [PATCH 03/14] Address MCP docs review feedback --- ai/mcp-server.mdx | 20 +++++++++++++++----- ai/mcp-server/setup.mdx | 17 +++++++---------- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index b7eecf95..96165eee 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -6,6 +6,12 @@ sidebarTitle: 'Overview' The Checkly MCP Server lets MCP-compatible AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation. +Use the production MCP endpoint in your client: + +```text +https://api.checklyhq.com/mcp +``` + 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. @@ -31,7 +37,6 @@ Before connecting an MCP client, ensure you have: - A Checkly user account. - Access to the Checkly account you want the MCP client to use. - An MCP-compatible client that supports Streamable HTTP and OAuth. -- The Checkly MCP endpoint: `https://api.checklyhq.com/mcp`. Add the Checkly MCP endpoint to your client, complete the OAuth flow, then ask your client to verify the connection: @@ -74,14 +79,19 @@ Trigger the checks tagged production-smoke, then follow the test session until r Create a major status page incident for the API outage, but do not notify subscribers until I confirm the message. ``` -## MCP vs Skills +## MCP, Skills, and CLI + +MCP, Checkly Skills, and the Checkly CLI are complementary. The CLI can also read live Checkly data and remains the most capable path for scripted workflows and local Monitoring as Code projects. + +Use the MCP Server when you want a quick, OAuth-based connection from an MCP-compatible client without setting up the Checkly CLI in that environment. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project. | Use case | Recommended path | | --- | --- | -| Read live Checkly account data | MCP Server | -| Trigger existing deployed checks | MCP Server | +| Ask quick, ad hoc questions from an MCP-compatible client | MCP Server | +| Inspect live Checkly data without local CLI setup | MCP Server | +| Trigger existing deployed checks from chat | MCP Server or [Checkly CLI](/cli/overview) | | Create or edit check code | [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview) | -| Test or deploy local Monitoring as Code projects | [Checkly CLI](/cli/overview) | +| Test, deploy, or automate local Monitoring as Code projects | [Checkly CLI](/cli/overview) | | Add reusable Checkly best practices to an agent | [Checkly Skills](/ai/skills) | ## Learn more diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index 51edcb0f..e2838aa7 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -1,28 +1,25 @@ --- title: 'Set up the Checkly MCP Server' description: 'Configure an MCP-compatible client to connect to the Checkly MCP Server over Streamable HTTP.' -sidebarTitle: 'Set up' +sidebarTitle: 'Setup' --- +Use the production MCP endpoint in your client: + +```text +https://api.checklyhq.com/mcp +``` + Before setting up the Checkly MCP Server, ensure you have: - A Checkly user account. - Access to the Checkly account you want your MCP client to use. - An MCP-compatible client that supports Streamable HTTP and OAuth. -- The Checkly MCP endpoint: `https://api.checklyhq.com/mcp`. The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives access to the Checkly tools it can use. -## Endpoint - -Use the production MCP endpoint: - -```text -https://api.checklyhq.com/mcp -``` - The server exposes protected-resource metadata for OAuth discovery. Most MCP clients discover this automatically when they connect to the endpoint. ## Codex From be8e366cda1dd341864c672160bc824a31bddb94 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Mon, 22 Jun 2026 11:25:00 +0200 Subject: [PATCH 04/14] Document MCP client registration requirements --- ai/mcp-server.mdx | 6 +++++- ai/mcp-server/security-and-permissions.mdx | 2 ++ ai/mcp-server/setup.mdx | 16 ++++++++++++---- ai/mcp-server/troubleshooting.mdx | 9 ++++++++- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 96165eee..d7d406de 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -12,6 +12,10 @@ Use the production MCP endpoint in your client: https://api.checklyhq.com/mcp ``` + +The Checkly MCP Server only supports MCP clients that use OAuth Client ID Metadata Documents (CIMD). Clients that use Dynamic Client Registration (DCR) are rejected. + + 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. @@ -36,7 +40,7 @@ Before connecting an MCP client, ensure you have: - A Checkly user account. - Access to the Checkly account you want the MCP client to use. -- An MCP-compatible client that supports Streamable HTTP and OAuth. +- An MCP-compatible client that supports Streamable HTTP and OAuth Client ID Metadata Documents (CIMD). Add the Checkly MCP endpoint to your client, complete the OAuth flow, then ask your client to verify the connection: diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index fa145d50..c225dadf 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -10,6 +10,8 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 public MCP Server only supports OAuth clients that use Client ID Metadata Documents (CIMD). Checkly rejects clients that attempt to use Dynamic Client Registration (DCR). + Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. ## OAuth permissions diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index e2838aa7..a4961886 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 an MCP-compatible client to connect to the Checkly MCP Server over Streamable HTTP.' +description: 'Configure a CIMD-capable MCP client to connect to the Checkly MCP Server over Streamable HTTP.' sidebarTitle: 'Setup' --- @@ -10,17 +10,25 @@ Use the production MCP endpoint in your client: https://api.checklyhq.com/mcp ``` + +The Checkly MCP Server only supports MCP clients that use OAuth Client ID Metadata Documents (CIMD). Clients that only support Dynamic Client Registration (DCR) cannot connect. + + Before setting up the Checkly MCP Server, ensure you have: - A Checkly user account. - Access to the Checkly account you want your MCP client to use. -- An MCP-compatible client that supports Streamable HTTP and OAuth. +- An MCP-compatible client that supports Streamable HTTP and OAuth Client ID Metadata Documents (CIMD). The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives access to the Checkly tools it can use. -The server exposes protected-resource metadata for OAuth discovery. Most MCP clients discover this automatically when they connect to the endpoint. +The server exposes protected-resource metadata for OAuth discovery. Most compatible MCP clients discover this automatically when they connect to the endpoint. + +Checkly does not support Dynamic Client Registration (DCR) for the public MCP Server. If your client attempts to register dynamically during OAuth, Checkly rejects the connection. + +The examples below assume your client version supports CIMD. If your client only supports DCR, the OAuth flow will fail. ## Codex @@ -83,7 +91,7 @@ Restart VS Code after changing the configuration. ## Other MCP clients -For clients that accept a generic `mcpServers` configuration, use: +For CIMD-capable clients that accept a generic `mcpServers` configuration, use: ```json mcp.json { diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index 3a8f6500..1b1f7398 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -8,6 +8,7 @@ sidebarTitle: 'Troubleshooting' Before troubleshooting, confirm: - Your MCP client is configured with `https://api.checklyhq.com/mcp`. +- Your MCP client supports OAuth Client ID Metadata Documents (CIMD). - You completed the OAuth login flow. - You restarted your MCP client after editing configuration. - Your Checkly user has access to the account you want to use. @@ -28,6 +29,12 @@ For Codex, run: codex mcp login checkly ``` +## OAuth registration fails + +The Checkly MCP Server supports OAuth Client ID Metadata Documents (CIMD). It 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 supports CIMD. Clients that only support DCR cannot connect to the public Checkly MCP Server. + ## No tools are listed Visible tools depend on the OAuth permissions granted to the MCP session. If no tools appear: @@ -87,4 +94,4 @@ 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. Try a command-line client such as Codex or Claude Code. -2. Confirm the client supports Streamable HTTP MCP servers with OAuth. +2. Confirm the client supports Streamable HTTP MCP servers with OAuth Client ID Metadata Documents (CIMD). From 1b7bf87f514af765d3ec010016f607dd4a19d9c2 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Mon, 22 Jun 2026 11:30:32 +0200 Subject: [PATCH 05/14] Link MCP OAuth registration references --- ai/mcp-server/security-and-permissions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index c225dadf..1e05d51c 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -10,7 +10,7 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 public MCP Server only supports OAuth clients that use Client ID Metadata Documents (CIMD). Checkly rejects clients that attempt to use Dynamic Client Registration (DCR). +The public MCP Server only supports OAuth clients that use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. From 4a8b6e396855b25ef6c64023c19bedf87da245a8 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Mon, 22 Jun 2026 11:31:51 +0200 Subject: [PATCH 06/14] Link MCP setup OAuth registration references --- ai/mcp-server/setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index a4961886..d81fdf72 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -11,7 +11,7 @@ https://api.checklyhq.com/mcp ``` -The Checkly MCP Server only supports MCP clients that use OAuth Client ID Metadata Documents (CIMD). Clients that only support Dynamic Client Registration (DCR) cannot connect. +The Checkly MCP Server only supports MCP clients that use [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Clients that only support [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) cannot connect. From 7832be098b594ca5cf1e886736651e4ad415a4f7 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Mon, 22 Jun 2026 16:33:49 +0200 Subject: [PATCH 07/14] Document MCP client compatibility caveats --- ai/mcp-server/setup.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index d81fdf72..bdf25047 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -108,6 +108,16 @@ For CIMD-capable clients that accept a generic `mcpServers` configuration, use: Omit `headers` if you want Checkly to resolve the account from tool arguments or your user membership. +## Known client limitations + +Some MCP clients support remote MCP servers but do not yet support the OAuth registration mode Checkly requires. If your preferred client cannot connect, [share feedback or requests](https://feedback.checklyhq.com). + +### Cline + +Cline is not currently supported for Checkly MCP OAuth. Cline's MCP OAuth flow requires Dynamic Client Registration, which Checkly does not enable. + +We can support Cline once it supports CIMD or pre-registered static OAuth clients for MCP servers. You can follow or upvote Cline's [static OAuth credentials request](https://github.com/cline/cline/discussions/10289). + ## Choose an account Most tools need an account context. Checkly resolves the account in this order: From fdfaa16aa5b591948caab2d72c4e3ce4f3717c91 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Tue, 23 Jun 2026 13:29:30 +0200 Subject: [PATCH 08/14] Document additional MCP client limitations --- ai/mcp-server/setup.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index bdf25047..57f1312b 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -118,6 +118,18 @@ Cline is not currently supported for Checkly MCP OAuth. Cline's MCP OAuth flow r We can support Cline once it supports CIMD or pre-registered static OAuth clients for MCP servers. You can follow or upvote Cline's [static OAuth credentials request](https://github.com/cline/cline/discussions/10289). +### Windsurf / Devin Desktop + +[Windsurf / Devin Desktop](https://docs.devin.ai/desktop/cascade/mcp) is not currently supported for Checkly MCP OAuth. It supports remote MCP servers with OAuth, but Checkly does not currently have a supported CIMD or pre-registered static OAuth setup for Windsurf / Devin Desktop. + +We can support Windsurf / Devin Desktop once it supports CIMD or pre-registered static OAuth clients for custom MCP servers. + +### Devin CLI + +[Devin CLI](https://docs.devin.ai/cli/extensibility/mcp/configuration) is not currently supported for Checkly MCP OAuth. Devin CLI supports pre-registered OAuth clients through `oauthClientId` and `oauthClientSecret`, but Checkly does not currently publish a pre-registered Devin OAuth client configuration for the public MCP Server. + +We can support Devin CLI once CIMD support or a Checkly-provided static OAuth setup is available. + ## Choose an account Most tools need an account context. Checkly resolves the account in this order: From 0da65e57c29bcc2a648049b88345ae5dbde11226 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Tue, 23 Jun 2026 13:38:48 +0200 Subject: [PATCH 09/14] Address MCP docs review follow-ups --- ai/mcp-server/security-and-permissions.mdx | 17 ++++++++++++++++- ai/mcp-server/troubleshooting.mdx | 4 ++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index 1e05d51c..a079b797 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -39,9 +39,24 @@ Tools are filtered from `tools/list` when the MCP session does not include the r Most tools operate on one Checkly account. Checkly resolves the account in this order: 1. `accountId` in the tool arguments. -2. `X-Checkly-Account` on the MCP connection. +2. `X-Checkly-Account` on the MCP connection, if your client supports custom headers. 3. Your sole account, if your user belongs to exactly one account. +Most clients configure headers in the MCP server entry. For example: + +```json mcp.json +{ + "mcpServers": { + "checkly": { + "url": "https://api.checklyhq.com/mcp", + "headers": { + "X-Checkly-Account": "" + } + } + } +} +``` + If you belong to multiple accounts and no account can be resolved, the tool returns a message with the accounts available to your session. Accounts that require mTLS are not available through the MCP Server. diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index 1b1f7398..91f3f188 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -23,6 +23,10 @@ If your client reports that authentication is required or invalid: 3. Remove stale Checkly MCP credentials from the client if it keeps reusing an old token. 4. Reconnect and call `whoami`. + +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. + + For Codex, run: ```bash Terminal From 37197c05c960da8c84fb973be851d487af06d85c Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Tue, 23 Jun 2026 13:39:56 +0200 Subject: [PATCH 10/14] Simplify MCP overview compatibility note --- ai/mcp-server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index d7d406de..5daf38e3 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -13,7 +13,7 @@ https://api.checklyhq.com/mcp ``` -The Checkly MCP Server only supports MCP clients that use OAuth Client ID Metadata Documents (CIMD). Clients that use Dynamic Client Registration (DCR) are rejected. +The Checkly MCP Server only supports some MCP clients today. Review the [setup requirements](/ai/mcp-server/setup) before connecting your client. 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. From 4fd2110ca8ed99070cc948bb1a88e3438a8ab3b3 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Tue, 23 Jun 2026 14:37:35 +0200 Subject: [PATCH 11/14] Update MCP server docs feedback --- ai/mcp-server.mdx | 16 +-- ai/mcp-server/security-and-permissions.mdx | 33 ++---- ai/mcp-server/setup.mdx | 132 +++++++++++---------- ai/mcp-server/tools.mdx | 18 ++- ai/mcp-server/troubleshooting.mdx | 26 ++-- 5 files changed, 115 insertions(+), 110 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 5daf38e3..47f4cd31 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -1,10 +1,10 @@ --- title: 'Checkly MCP Server' -description: 'Connect MCP-compatible AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.' +description: 'Connect supported AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.' sidebarTitle: 'Overview' --- -The Checkly MCP Server lets MCP-compatible AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation. +The Checkly MCP Server lets supported AI 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 ``` -The Checkly MCP Server only supports some MCP clients today. Review the [setup requirements](/ai/mcp-server/setup) before connecting your client. +The Checkly MCP Server only supports Checkly-approved clients that use OAuth Client ID Metadata Documents (CIMD). Clients that use Dynamic Client Registration (DCR) are rejected. See [setup requirements](/ai/mcp-server/setup) for supported clients and details. 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,16 +40,16 @@ Before connecting an MCP client, ensure you have: - A Checkly user account. - Access to the Checkly account you want the MCP client to use. -- An MCP-compatible client that supports Streamable HTTP and OAuth Client ID Metadata Documents (CIMD). +- A [supported MCP client](/ai/mcp-server/setup#supported-clients). -Add the Checkly MCP endpoint to your client, 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: ```text title="Prompt" wrap Use Checkly to show which accounts I can access. ``` -If you belong to more than one Checkly account, set the account in your client configuration with the `X-Checkly-Account` header when your client supports headers, or pass `accountId` in tool calls. +If you belong to more than one Checkly account, tell your client which account to use in your prompt. To always use the same account, set the `X-Checkly-Account` header when your client supports custom MCP headers. See [Set up the MCP server](/ai/mcp-server/setup) for client configuration examples. @@ -87,11 +87,11 @@ Create a major status page incident for the API outage, but do not notify subscr MCP, Checkly Skills, and the Checkly CLI are complementary. The CLI can also read live Checkly data and remains the most capable path for scripted workflows and local Monitoring as Code projects. -Use the MCP Server when you want a quick, OAuth-based connection from an MCP-compatible client without setting up the Checkly CLI in that environment. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project. +Use the MCP Server when you want a quick, OAuth-based connection from a supported client without setting up the Checkly CLI in that environment. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project. | Use case | Recommended path | | --- | --- | -| Ask quick, ad hoc questions from an MCP-compatible client | MCP Server | +| Ask quick, ad hoc questions from a supported client | MCP Server | | Inspect live Checkly data without local CLI setup | MCP Server | | Trigger existing deployed checks from chat | MCP Server or [Checkly CLI](/cli/overview) | | Create or edit check code | [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview) | diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index a079b797..8a5fb6e4 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -1,6 +1,6 @@ --- title: 'MCP security and permissions' -description: 'Understand how the Checkly MCP Server authenticates users, filters tools by permission, resolves account context, and handles write actions.' +description: 'Understand how the Checkly MCP Server authenticates users, filters tools by permission, handles account context, and protects write actions.' sidebarTitle: 'Security & permissions' --- @@ -10,7 +10,7 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 public MCP Server only supports OAuth clients that use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). +The public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Supported clients use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [known client limitations](setup#known-client-limitations) for unsupported clients. Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. @@ -34,32 +34,13 @@ Checkly maps the token subject to a Checkly user, then loads that user's account 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 resolution +## Account context -Most tools operate on one Checkly account. Checkly resolves the account in this order: +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](setup#use-a-specific-account) for setup examples. -1. `accountId` in the tool arguments. -2. `X-Checkly-Account` on the MCP connection, if your client supports custom headers. -3. Your sole account, if your user belongs to exactly one account. - -Most clients configure headers in the MCP server entry. For example: - -```json mcp.json -{ - "mcpServers": { - "checkly": { - "url": "https://api.checklyhq.com/mcp", - "headers": { - "X-Checkly-Account": "" - } - } - } -} -``` - -If you belong to multiple accounts and no account can be resolved, the tool returns a message with the accounts available to your session. - -Accounts that require mTLS are not available through the MCP Server. + +Accounts that require mTLS are not available through the public MCP Server. + ## Role checks diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index 57f1312b..ea1a7fd3 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 a CIMD-capable MCP client to connect to the Checkly MCP Server over Streamable HTTP.' +description: 'Configure a supported MCP client to connect to the Checkly MCP Server over Streamable HTTP.' sidebarTitle: 'Setup' --- @@ -11,40 +11,31 @@ https://api.checklyhq.com/mcp ``` -The Checkly MCP Server only supports MCP clients that use [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Clients that only support [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) cannot connect. +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. - -Before setting up the Checkly MCP Server, ensure you have: +## Supported clients -- A Checkly user account. -- Access to the Checkly account you want your MCP client to use. -- An MCP-compatible client that supports Streamable HTTP and OAuth Client ID Metadata Documents (CIMD). - +The public Checkly MCP Server currently supports: -The Checkly MCP Server uses OAuth. Your MCP client connects to the endpoint, opens a browser-based login flow, and receives access to the Checkly tools it can use. +- ChatGPT +- Claude Desktop +- Claude Code +- Antigravity +- Cursor +- VS Code -The server exposes protected-resource metadata for OAuth discovery. Most compatible MCP clients discover this automatically when they connect to the endpoint. +Each supported client uses [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) and must be allowed by Checkly in Auth0 before it can connect. Clients that rely on DCR are not supported. -Checkly does not support Dynamic Client Registration (DCR) for the public MCP Server. If your client attempts to register dynamically during OAuth, Checkly rejects the connection. +If you want Checkly to support another CIMD-capable client, [share feedback or requests](https://feedback.checklyhq.com). -The examples below assume your client version supports CIMD. If your client only supports DCR, the OAuth flow will fail. +## ChatGPT -## Codex +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. -Add the server: +## Claude Desktop -```bash Terminal -codex mcp add checkly --url https://api.checklyhq.com/mcp -``` - -Then log in: - -```bash Terminal -codex mcp login checkly -``` - -Restart Codex after adding the server. +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 @@ -56,6 +47,10 @@ claude mcp add --transport http checkly https://api.checklyhq.com/mcp Start a Claude Code session and 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. + ## Cursor Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects: @@ -64,7 +59,26 @@ Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` { "mcpServers": { "checkly": { - "url": "https://api.checklyhq.com/mcp" + "type": "http", + "url": "https://api.checklyhq.com/mcp", + "auth": { + "CLIENT_ID": "tpc_6UZKE6SnYVKGZKExoSK3FT", + "scopes": [ + "checkly:account:read", + "checkly:account:invite", + "checkly:checks:read", + "checkly:checks:run", + "checkly:incidents:read", + "checkly:incidents:write", + "checkly:environment-variables:read", + "checkly:environment-variables:write", + "checkly:status-pages:read", + "checkly:rca:read", + "checkly:rca:run", + "checkly:test-sessions:read", + "checkly:assets:read" + ] + } } } } @@ -89,56 +103,54 @@ Add the server to `.vscode/mcp.json` in your workspace, or to your VS Code user Restart VS Code after changing the configuration. -## Other MCP clients - -For CIMD-capable clients that accept a generic `mcpServers` configuration, use: - -```json mcp.json -{ - "mcpServers": { - "checkly": { - "url": "https://api.checklyhq.com/mcp", - "headers": { - "X-Checkly-Account": "" - } - } - } -} -``` - -Omit `headers` if you want Checkly to resolve the account from tool arguments or your user membership. - ## Known client limitations -Some MCP clients support remote MCP servers but do not yet support the OAuth registration mode Checkly requires. If your preferred client cannot connect, [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 yet. If your preferred CIMD-capable client is missing, [share feedback or requests](https://feedback.checklyhq.com). ### Cline -Cline is not currently supported for Checkly MCP OAuth. Cline's MCP OAuth flow requires Dynamic Client Registration, which Checkly does not enable. - -We can support Cline once it supports CIMD or pre-registered static OAuth clients for MCP servers. You can follow or upvote Cline's [static OAuth credentials request](https://github.com/cline/cline/discussions/10289). +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). ### Windsurf / Devin Desktop -[Windsurf / Devin Desktop](https://docs.devin.ai/desktop/cascade/mcp) is not currently supported for Checkly MCP OAuth. It supports remote MCP servers with OAuth, but Checkly does not currently have a supported CIMD or pre-registered static OAuth setup for Windsurf / Devin Desktop. - -We can support Windsurf / Devin Desktop once it supports CIMD or pre-registered static OAuth clients for custom MCP servers. +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). ### Devin CLI -[Devin CLI](https://docs.devin.ai/cli/extensibility/mcp/configuration) is not currently supported for Checkly MCP OAuth. Devin CLI supports pre-registered OAuth clients through `oauthClientId` and `oauthClientSecret`, but Checkly does not currently publish a pre-registered Devin OAuth client configuration for the public MCP Server. +Devin CLI 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). + +## Use a specific account -We can support Devin CLI once CIMD support or a Checkly-provided static OAuth setup is available. +If you belong to multiple Checkly accounts, tell your MCP client which account you want to use in your prompt: -## Choose an account +```text title="Prompt" wrap +Use Checkly to show the accounts I can access, then show failing checks for . +``` + +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: + +```bash Terminal +claude mcp add --transport http checkly https://api.checklyhq.com/mcp --header "X-Checkly-Account: " +``` -Most tools need an account context. Checkly resolves the account in this order: +For clients that use an `mcpServers` JSON configuration, add `headers` to the Checkly server entry: -1. The `accountId` argument passed to the tool. -2. The `X-Checkly-Account` header on the MCP connection. -3. Your sole account, if your user belongs to exactly one account. +```json mcp.json +{ + "mcpServers": { + "checkly": { + "url": "https://api.checklyhq.com/mcp", + "headers": { + "X-Checkly-Account": "" + } + } + } +} +``` -If you belong to multiple accounts and do not provide an account, the tool returns a message with the accounts you can access. +Use the account ID from Checkly. Omit the header when you want to choose the account in your prompts. ## Verify the connection diff --git a/ai/mcp-server/tools.mdx b/ai/mcp-server/tools.mdx index 819652e8..f300dbfe 100644 --- a/ai/mcp-server/tools.mdx +++ b/ai/mcp-server/tools.mdx @@ -32,18 +32,30 @@ Prepare the local Checkly CLI steps to create a browser check for checkout. | Tool | Type | Description | | --- | --- | --- | -| `get-check-status` | Read | Return current status for checks in the account, including check type, activation state, and passing or failing state. | -| `list-check-results` | Read | List recent compact results for one check. Raw logs, traces, screenshots, videos, and download URLs are omitted. | +| `get-check-status` | Read | Return a paginated, filterable list of current check status rows, including check type, activation state, and passing, degraded, or failing state. | +| `list-check-results` | Read | List recent compact results for one check, including HTTP response status and assertion counts when available. Raw logs, traces, screenshots, videos, and download URLs are omitted. | | `get-check-result` | Read | Return compact detail for one check result. | | `get-check-performance-summary` | Read | Return average, P50, P95, and P99 response-time metrics for one check over a date range when data is available. | | `trigger-checks` | Write | Run existing deployed checks on demand and record the run as a test session. Consumes check-run execution quota. | +For large accounts, start with `get-check-status` filters instead of asking for every check at once. The tool supports: + +- `tag`: filter by one or more tags. +- `type` or `checkType`: filter by check type. +- `search`: filter by check name. +- `status`: filter by `passing`, `failing`, or `degraded`. +- `limit` and `page`: page through matching checks. The default page size is 25 and the maximum is 100. + +The response includes pagination metadata (`length`, `total`, `page`, `limit`, and `totalPages`) plus the applied `filters`, so your client can continue with the next page only when needed. + +`list-check-results` stays compact for fast triage. Result rows include `responseStatusCode`, `responseStatusText`, `totalAssertions`, and `failingAssertions` when available, so your client can inspect common URL and API failure signals before fetching full result details or assets. + `trigger-checks` only runs checks that already exist on the account. Use `prepare-local-check-authoring` and the Checkly CLI when you need to create, test, or deploy local check code. Example prompts: ```text title="Prompt" wrap -Show me failing checks and summarize what changed in their latest results. +Show me the first page of failing API checks tagged production, then summarize what changed in their latest results. ``` ```text title="Prompt" wrap diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index 91f3f188..f3877898 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -8,7 +8,7 @@ sidebarTitle: 'Troubleshooting' Before troubleshooting, confirm: - Your MCP client is configured with `https://api.checklyhq.com/mcp`. -- Your MCP client supports OAuth Client ID Metadata Documents (CIMD). +- Your MCP client is in the [supported clients list](/ai/mcp-server/setup#supported-clients). - You completed the OAuth login flow. - You restarted your MCP client after editing configuration. - Your Checkly user has access to the account you want to use. @@ -27,17 +27,11 @@ If your client reports that authentication is required or invalid: 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. -For Codex, run: - -```bash Terminal -codex mcp login checkly -``` - ## OAuth registration fails -The Checkly MCP Server supports OAuth Client ID Metadata Documents (CIMD). It does not support Dynamic Client Registration (DCR). +The Checkly MCP Server only supports clients that Checkly has approved in Auth0. Supported clients use OAuth Client ID Metadata Documents (CIMD). 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 supports CIMD. Clients that only support DCR cannot connect to the public Checkly MCP Server. +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. ## No tools are listed @@ -60,16 +54,20 @@ Each tool requires an OAuth permission. For example: See [MCP tools](/ai/mcp-server/tools) for the full tool list. +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 -If you belong to multiple Checkly accounts, pass `accountId` in the tool call or configure the `X-Checkly-Account` header when your client supports headers. +If you belong to multiple Checkly accounts, tell your MCP client which account to use in your prompt. Ask your client: ```text title="Prompt" wrap -Use Checkly to show the accounts I can access, then use accountId for the next Checkly request. +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). + ## 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,6 +84,8 @@ Then run the returned Checkly CLI steps in your local project. 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. + Before approving write tool calls, check: - The target account ID. @@ -97,5 +97,5 @@ 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. Try a command-line client such as Codex or Claude Code. -2. Confirm the client supports Streamable HTTP MCP servers with OAuth Client ID Metadata Documents (CIMD). +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. From cfb201011952ab751203b1affa0f6c1db8ea5c87 Mon Sep 17 00:00:00 2001 From: Herve Labas Date: Tue, 23 Jun 2026 14:42:08 +0200 Subject: [PATCH 12/14] Fix MCP security setup links --- ai/mcp-server/security-and-permissions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index 8a5fb6e4..6783d179 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -10,7 +10,7 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Supported clients use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [known client limitations](setup#known-client-limitations) for unsupported clients. +The public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Supported clients use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [known client limitations](/ai/mcp-server/setup#known-client-limitations) for unsupported clients. Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. @@ -36,7 +36,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](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 [Use a specific account](/ai/mcp-server/setup#use-a-specific-account) for setup examples. Accounts that require mTLS are not available through the public MCP Server. From ee11f6bd95b5c2d34401454e06db6c22549d8dcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Labas?= <431257+thebiglabasky@users.noreply.github.com> Date: Wed, 24 Jun 2026 11:12:54 +0200 Subject: [PATCH 13/14] Add Devin CLI MCP setup docs (#399) * Add Devin CLI MCP setup docs * Address MCP static client review feedback --- ai/mcp-server.mdx | 2 +- ai/mcp-server/security-and-permissions.mdx | 2 +- ai/mcp-server/setup.mdx | 49 +++++++++++++++------- ai/mcp-server/troubleshooting.mdx | 2 +- 4 files changed, 38 insertions(+), 17 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 47f4cd31..0eec86f2 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -13,7 +13,7 @@ https://api.checklyhq.com/mcp ``` -The Checkly MCP Server only supports Checkly-approved clients that use OAuth Client ID Metadata Documents (CIMD). Clients that use Dynamic Client Registration (DCR) are rejected. See [setup requirements](/ai/mcp-server/setup) for supported clients and details. +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. 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. diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index 6783d179..156f5abe 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -10,7 +10,7 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Supported clients use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [known client limitations](/ai/mcp-server/setup#known-client-limitations) for unsupported clients. +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. Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index ea1a7fd3..cf520b25 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -16,18 +16,21 @@ The Checkly MCP Server only supports the clients listed below. Clients that use ## Supported clients -The public Checkly MCP Server currently supports: +The public Checkly MCP Server currently supports these clients: -- ChatGPT -- Claude Desktop -- Claude Code -- Antigravity -- Cursor -- 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. | +| 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. | -Each supported client uses [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) and must be allowed by Checkly in Auth0 before it can connect. Clients that rely on DCR are not supported. +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 and Devin CLI use Checkly's static MCP OAuth clients. Clients that rely on DCR are not supported. -If you want Checkly to support another CIMD-capable client, [share feedback or requests](https://feedback.checklyhq.com). +If you want Checkly to support another compatible client, [share feedback or requests](https://feedback.checklyhq.com). ## ChatGPT @@ -47,6 +50,28 @@ claude mcp add --transport http checkly https://api.checklyhq.com/mcp Start a Claude Code session and complete the OAuth flow when prompted. +## Devin CLI + +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. @@ -105,7 +130,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 CIMD-capable 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 yet. If your preferred compatible client is missing, [share feedback or requests](https://feedback.checklyhq.com). ### Cline @@ -115,10 +140,6 @@ Cline is not currently supported for Checkly MCP OAuth because of its current OA 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). -### Devin CLI - -Devin CLI 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). - ## Use a specific account If you belong to multiple Checkly accounts, tell your MCP client which account you want to use in your prompt: diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index f3877898..f5e67af7 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -29,7 +29,7 @@ If the browser login page shows an Auth0 "Something went wrong" error, contact [ ## OAuth registration fails -The Checkly MCP Server only supports clients that Checkly has approved in Auth0. Supported clients use OAuth Client ID Metadata Documents (CIMD). Checkly does not support Dynamic Client Registration (DCR). +The Checkly MCP Server only supports clients that Checkly has approved in Auth0. 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. From b7fe57a0c31c6b5bc1d6070793a768ad5946680d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Labas?= <431257+thebiglabasky@users.noreply.github.com> Date: Wed, 24 Jun 2026 11:32:48 +0200 Subject: [PATCH 14/14] Revert "Add Devin CLI MCP setup docs (#399)" This reverts commit ee11f6bd95b5c2d34401454e06db6c22549d8dcb. --- ai/mcp-server.mdx | 2 +- ai/mcp-server/security-and-permissions.mdx | 2 +- ai/mcp-server/setup.mdx | 49 +++++++--------------- ai/mcp-server/troubleshooting.mdx | 2 +- 4 files changed, 17 insertions(+), 38 deletions(-) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 0eec86f2..47f4cd31 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -13,7 +13,7 @@ https://api.checklyhq.com/mcp ``` -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. +The Checkly MCP Server only supports Checkly-approved clients that use OAuth Client ID Metadata Documents (CIMD). Clients that use Dynamic Client Registration (DCR) are rejected. See [setup requirements](/ai/mcp-server/setup) for supported clients and details. 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. diff --git a/ai/mcp-server/security-and-permissions.mdx b/ai/mcp-server/security-and-permissions.mdx index 156f5abe..6783d179 100644 --- a/ai/mcp-server/security-and-permissions.mdx +++ b/ai/mcp-server/security-and-permissions.mdx @@ -10,7 +10,7 @@ The Checkly MCP Server uses OAuth and Checkly account authorization together. OA 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 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. +The public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Supported clients use [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [known client limitations](/ai/mcp-server/setup#known-client-limitations) for unsupported clients. Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls. diff --git a/ai/mcp-server/setup.mdx b/ai/mcp-server/setup.mdx index cf520b25..ea1a7fd3 100644 --- a/ai/mcp-server/setup.mdx +++ b/ai/mcp-server/setup.mdx @@ -16,21 +16,18 @@ The Checkly MCP Server only supports the clients listed below. Clients that use ## Supported clients -The public Checkly MCP Server currently supports these clients: +The public Checkly MCP Server currently supports: -| 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. | -| 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. | +- ChatGPT +- Claude Desktop +- Claude Code +- Antigravity +- Cursor +- VS Code -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 and Devin CLI use Checkly's static MCP OAuth clients. Clients that rely on DCR are not supported. +Each supported client uses [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) and must be allowed by Checkly in Auth0 before it can connect. 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). +If you want Checkly to support another CIMD-capable client, [share feedback or requests](https://feedback.checklyhq.com). ## ChatGPT @@ -50,28 +47,6 @@ claude mcp add --transport http checkly https://api.checklyhq.com/mcp Start a Claude Code session and complete the OAuth flow when prompted. -## Devin CLI - -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. @@ -130,7 +105,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 yet. If your preferred CIMD-capable client is missing, [share feedback or requests](https://feedback.checklyhq.com). ### Cline @@ -140,6 +115,10 @@ Cline is not currently supported for Checkly MCP OAuth because of its current OA 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). +### Devin CLI + +Devin CLI 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). + ## Use a specific account If you belong to multiple Checkly accounts, tell your MCP client which account you want to use in your prompt: diff --git a/ai/mcp-server/troubleshooting.mdx b/ai/mcp-server/troubleshooting.mdx index f5e67af7..f3877898 100644 --- a/ai/mcp-server/troubleshooting.mdx +++ b/ai/mcp-server/troubleshooting.mdx @@ -29,7 +29,7 @@ If the browser login page shows an Auth0 "Something went wrong" error, contact [ ## 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 clients that Checkly has approved in Auth0. Supported clients use OAuth Client ID Metadata Documents (CIMD). 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.