Improve MCP docs setup and auth flow (#438)

Author: thebiglabasky

ai/mcp-server.mdx

@@ -14,7 +14,7 @@ https://api.checklyhq.com/mcp
 ```
 
 <Warning>
-OAuth is the recommended way to connect. The OAuth flow only supports Checkly-approved clients listed in setup. API-key authentication is available for non-interactive clients that can send custom headers, but you are responsible for protecting and rotating the key.
+OAuth is the recommended way to connect. The OAuth flow only supports Checkly-approved clients listed in setup. User and service API keys are available for clients that can send custom headers when OAuth is unavailable or a workflow needs a stable service identity.
 </Warning>
 
 Use it when your agent needs live Checkly account context, check status, check results, test sessions, root cause analyses, result assets, status pages, incidents, account environment variables, or when it needs to trigger existing checks.
@@ -41,10 +41,10 @@ Before connecting an MCP client, ensure you have:
 
 - A Checkly user account.
 - Access to the Checkly account you want the MCP client to use.
-- A [supported OAuth MCP client](/ai/mcp-server/setup#supported-clients), or an MCP client that can send custom HTTP headers for API-key authentication.
+- A [supported OAuth MCP client](/ai/mcp-server/setup#supported-oauth-clients), or an MCP client that can send custom HTTP headers for API-key authentication.
 </Accordion>
 
-[Add the Checkly MCP endpoint to your client](/ai/mcp-server/setup), complete the OAuth flow, then ask your client to verify the connection. If your client cannot complete OAuth but can send custom headers, configure API-key authentication instead.
+[Choose an authentication method and add the Checkly MCP endpoint to your client](/ai/mcp-server/setup#choose-an-authentication-method). Complete OAuth or configure an API-key header, then ask your client to verify the connection.
 
 ```text title="Prompt" wrap
 Use Checkly to show which accounts I can access.
@@ -86,7 +86,7 @@ Create a major status page incident for the API outage, but do not notify subscr
 
 ## MCP, Skills, and CLI
 
-MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for a quick OAuth-based connection from a supported client. Use API-key authentication only when OAuth is not practical for a non-interactive workflow. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project.
+MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for quick access to live Checkly data and account actions. OAuth is the recommended connection method; use an API key when OAuth is unavailable or when automation needs an account-scoped service identity. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project.
 
 See [Skills, MCP, and the CLI](/ai/overview#skills-mcp-and-the-cli) for a full comparison of when to use each.
 

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

@@ -14,12 +14,12 @@ The MCP Server accepts two types of bearer tokens for `https://api.checklyhq.com
 - OAuth bearer tokens from Checkly-approved MCP clients.
 - Checkly user API keys starting with `cu_...`, and service API keys starting with `sv_...`, sent as `Authorization: Bearer <checkly-api-key>`.
 
-OAuth is recommended for interactive clients. The public MCP Server only supports Checkly-approved OAuth clients. Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [supported clients](/ai/mcp-server/setup#supported-clients) for setup details.
+OAuth is recommended for interactive clients. The public MCP Server only supports Checkly-approved OAuth clients. Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [supported OAuth clients](/ai/mcp-server/setup#supported-oauth-clients) or [set up an API key](/ai/mcp-server/setup#set-up-with-an-api-key).
 
 Checkly maps OAuth tokens and user API keys to a Checkly user, then loads that user's account memberships and account context for tool calls. Service API keys map to the key's configured account and role.
 
 <Warning>
-API keys are long-lived credentials. Use API-key authentication only when OAuth is not practical, store keys securely, and rotate them when they are no longer needed.
+API keys are long-lived credentials. Use them when OAuth is unavailable or a workflow needs a service identity. Store keys securely and rotate them when they are no longer needed.
 </Warning>
 
 ## Session permissions
@@ -46,7 +46,7 @@ Tools are filtered from `tools/list` when the MCP session does not include the r
 
 ## Account context
 
-Most tools operate on one Checkly account. You can select a specific account in your prompt or pin an account in your MCP client configuration. See [Use a specific account](/ai/mcp-server/setup#use-a-specific-account) for setup examples.
+Most tools operate on one Checkly account. You can select a specific account in your prompt or pin an account in your MCP client configuration. See [Select an account](/ai/mcp-server/setup#select-an-account) for setup examples.
 
 <Warning>
 Accounts that require mTLS are not available through the public MCP Server.