Add MCP server documentation

ai/mcp-server.mdx

@@ -0,0 +1,102 @@
+---
+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: '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.
+
+<Note>
+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.
+</Note>
+
+## 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
+
+<Accordion title="Before you begin">
+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.
+</Accordion>
+
+Add the Checkly MCP endpoint to your client, 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.
+
+See [Set up the MCP server](/ai/mcp-server/setup) for client configuration examples.
+
+## Example prompts
+
+Basic prompts:
+
+```text title="Prompt" wrap
+Show me the current status of my Checkly checks.
+```
+
+```text title="Prompt" wrap
+List open status page incidents.
+```
+
+```text title="Prompt" wrap
+What features are available on my current Checkly plan?
+```
+
+Advanced prompts:
+
+```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 title="Prompt" wrap
+Trigger the checks tagged production-smoke, then follow the test session until results are available.
+```
+
+```text title="Prompt" wrap
+Create a major status page incident for the API outage, but do not notify subscribers until I confirm the message.
+```
+
+## 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 |
+| --- | --- |
+| 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, 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
+
+- [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)

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 permission, resolves account context, and handles write actions.'
+sidebarTitle: 'Security & permissions'
+---
+
+The Checkly MCP Server uses OAuth and Checkly account authorization together. OAuth permissions decide which tools are visible to your MCP client. Checkly account membership, role, and feature entitlements decide whether a specific tool call can operate on an account.
+
+## 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.
+
+## OAuth permissions
+
+| Permission | Description |
+| --- | --- |
+| `checkly:account:read` | Read your Checkly account membership and status |
+| `checkly:account:invite` | Invite members to your Checkly account |
+| `checkly:checks:read` | List checks, their status and results |
+| `checkly:checks:run` | Trigger Checkly checks and on-demand test sessions |
+| `checkly:incidents:read` | Read your Checkly incidents |
+| `checkly:incidents:write` | Create and update your Checkly incidents |
+| `checkly:environment-variables:read` | Read your Checkly account environment variables (secret values excluded) |
+| `checkly:environment-variables:write` | Create, update and delete your Checkly account environment variables |
+| `checkly:status-pages:read` | Read your Checkly status pages |
+| `checkly:rca:read` | Read your Checkly root cause analyses |
+| `checkly:rca:run` | Run Checkly root cause analysis for your account |
+| `checkly:test-sessions:read` | Read your Checkly test sessions |
+| `checkly:assets:read` | Read your Checkly assets |
+
+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
+
+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 permission and a Checkly account role:
+
+| Tool or action | Additional account access required |
+| --- | --- |
+| `invite-account-member` | Owner or Admin |
+| `create-account-environment-variable` | Write access |
+| `update-account-environment-variable` | Write access |
+| `trigger-checks` | Run access |
+| `trigger-root-cause-analysis` | Run access |
+| Status page incident writes | Access required by the underlying incident action |
+
+## Write-action safety
+
+Some MCP tools create side effects:
+
+- `invite-account-member` sends an invite email and is not idempotent.
+- `trigger-checks` consumes check-run execution quota.
+- `trigger-root-cause-analysis` consumes RCA invocation quota.
+- `create-status-page-incident`, `update-status-page-incident`, and `resolve-status-page-incident` can notify subscribers and are not idempotent.
+- Environment variable write tools can create or replace account-level variables and secrets.
+
+Review write tool calls in your MCP client before approving them.
+
+## Secrets
+
+MCP read tools never reveal Checkly secret values. Secret values are returned as `null`.
+
+When you create or update a secret through MCP, Checkly encrypts the value and does not echo it back in the tool response.

ai/mcp-server/setup.mdx

@@ -0,0 +1,127 @@
+---
+title: 'Set up the Checkly MCP Server'
+description: 'Configure an MCP-compatible client to connect to the Checkly MCP Server over Streamable HTTP.'
+sidebarTitle: 'Setup'
+---
+
+Use the production MCP endpoint in your client:
+
+```text
+https://api.checklyhq.com/mcp
+```
+
+<Accordion title="Before you begin">
+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.
+</Accordion>
+
+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.
+
+## 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": "<account-id>"
+      }
+    }
+  }
+}
+```
+
+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 title="Prompt" wrap
+Use Checkly to show which accounts I can access.
+```
+
+Then verify tool access:
+
+```text title="Prompt" wrap
+Use Checkly to list the tools available to this session.
+```
+
+The visible tools depend on the OAuth permissions granted to your MCP session. See [Security and permissions](/ai/mcp-server/security-and-permissions) for details.