Skip to main content

Claude.ai custom connector

If you have Claude Pro or Claude Max, the custom-connector flow is the easiest way to use Site Health. No API key, no config file — just paste a URL and approve in your browser.

Prerequisites​

  • A Claude.ai account on the Pro or Max plan (custom connectors are not available on the free tier)
  • At least one Webflow site connected to Site Health with one completed scan

Setup​

  1. Open Claude.ai and click your avatar → Settings → Connectors.
  2. Click Add custom connector. You'll see a dialog with fields for name, URL, and optional OAuth credentials.
  3. Fill in:
    • Name: Site Health (or any name you want — this is what shows up in the tools menu)
    • Remote MCP server URL: https://sitehealth.octagramlabs.com/api/mcp
    • OAuth Client ID: leave empty
    • OAuth Client Secret: leave empty
  4. Click Add. Claude will open a new browser tab.
  5. Sign in to Site Health (if you aren't already). You'll land on a consent screen showing the mcp:read scope.
  6. Click Approve. The tab closes and the connector appears in your Claude.ai tools as "Connected."
  7. Start a new chat. You should see Site Health listed in the tools menu.

Leaving the OAuth fields empty is correct: Site Health supports Dynamic Client Registration (RFC 7591), so Claude can register itself automatically. If you paste a client ID that doesn't exist in our DB, the flow will fail.

Example prompts​

Once connected, try these:

  • "List my sites."
  • "Audit my latest scan for studio-brava."
  • "Why did Performance drop on my homepage since the last publish?"
  • "Generate a client report for studio-brava and give me the shareable URL."
  • "Which third-party script is hurting performance most across all my sites?"

Claude will call the correct MCP tool (list_sites, get_latest_scan, get_regression_report, generate_client_report, get_third_party_scripts) without you having to name them.

What happens technically​

  1. Dynamic Client Registration — Claude.ai POSTs to /api/oauth/register and gets back a client_id.
  2. Authorization with PKCE — Claude redirects you to /oauth/authorize?...&code_challenge=...&code_challenge_method=S256. Only S256 is supported (OAuth 2.1 disallows the plain method).
  3. Consent — you sign in and approve the mcp:read scope.
  4. Token exchange — the redirect returns a short-lived code (10-minute TTL). Claude POSTs it to /api/oauth/token along with the code_verifier. The server verifies the PKCE hash and issues a 30-day access token plus a 90-day refresh token.
  5. Tool calls — every MCP request carries Authorization: Bearer <access-token>.

Tokens are SHA-256 hashed before storage. The raw token is only ever sent back to Claude once, in the token-exchange response.

Revoking access​

Open Site Health → Settings → Connected Apps. You'll see each connected Claude client with its last-used timestamp. Click Revoke — all tokens for that client are immediately invalidated, and Claude's next request will 401.

If you run Claude Code from a terminal, install the Claude Code skill — it reuses the same OAuth connection. If you use the Claude Desktop app (not Claude.ai), see Claude Desktop — Desktop uses an API key, not OAuth.

Troubleshooting​

"redirect_uri mismatch" error during approval. Claude.ai's redirect URI is registered automatically via DCR. If you see this, the DCR call failed or you pasted a stale client_id into the OAuth Client ID field. Leave that field blank and retry.

Browser stuck on "Authorizing..." forever. The authorize endpoint uses a 303 redirect after consent (required by some clients). If your browser is blocking redirects or you have an aggressive privacy extension (uBlock, Privacy Badger on hardened mode), temporarily disable it, approve, then re-enable. Also check the Claude.ai browser tab for a dev-console error — a CSP violation will show up there.

Connector shows as "Connected" but no tools appear in chat. Start a brand-new chat — existing chats don't pick up newly added connectors. If tools still don't appear, open a clean Claude.ai tab (log out and back in refreshes the connector list).

Site Health returns "Site not found" when asking about a site. The access token is scoped to the user who approved it. If you have multiple Site Health accounts, make sure you signed in with the one that owns the site.