Improve MCP docs setup and authentication flow

[thebiglabasky]

Summary

• Reorganize MCP setup into a progressive flow: endpoint, authentication choice, OAuth client setup, API-key setup, account selection, and connection verification.
• Add explicit user API key versus service API key guidance, including account/role behavior, key creation, secure client examples, and focused troubleshooting.
• Add the missing Antigravity pre-registered OAuth configuration and replace the stale Codex callback-port limitation with a tested API-key setup path.
• Group troubleshooting by authentication, tools and permissions, account selection, local authoring, write actions, and browser clients.
• Add the shipped list-test-session-results tool to the tools reference.

Why

The OAuth client instructions grew incrementally, and the later API-key section was inserted in the middle of the client sequence. That made readers choose between auth methods and clients at the same level, while service-key account/role behavior was spread across setup, security, and troubleshooting. The Codex OAuth limitation also described callback-port behavior that is no longer current.

User impact

Readers now choose an auth method before entering client-specific instructions. OAuth remains the recommended interactive path, while user and service API keys have clear fallback and automation guidance. Troubleshooting follows the same structure as setup, making auth, role, account, and missing-tool failures easier to isolate.

Validation

• Cross-checked MCP auth, API-key prefixes/scopes, account resolution, and tool registry against current checkly/monorepo origin/main.
• Verified current client behavior against official OpenAI, Anthropic, Google Antigravity, OpenCode, Cursor, and VS Code documentation.
• Verified local claude, devin, opencode, and codex command syntax; exercised the Codex bearer-token setup in an isolated config.
• Parsed all JSON examples.
• Rendered and reviewed setup and troubleshooting in a local Mintlify preview.
• npm exec -- mint broken-links
• python3 .github/scripts/check_frontmatter.py
• python3 .github/scripts/check_redirect_destinations.py
• npm run generate-sitemap
• git diff --check

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
checkly-422f444a	🟢 Ready	View Preview	Jul 10, 2026, 2:33 PM