Skip to main content

Cursor and Windsurf

Cursor and Windsurf both support MCP over HTTP with bearer authentication. Setup is almost identical to Claude Desktop — same JSON shape, same auth header, different config file location. Neither client supports OAuth yet, so you authenticate with a Site Health API key.

Prerequisites​

  • Cursor ≥ 0.42 or Windsurf latest
  • A Site Health API key from Settings → API Keys (see Claude Desktop for how to create one)

Cursor​

  1. Open Cursor.
  2. Settings (Cmd/Ctrl + ,) → Features → Model Context Protocol → Add new MCP server.
  3. Cursor opens the MCP config file. Paste:
{
  "mcpServers": {
    "site-health": {
      "url": "https://sitehealth.octagramlabs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SITE_HEALTH_API_KEY"
      }
    }
  }
}
  1. Save the file. Cursor watches the file and reloads MCP servers automatically — no restart needed.
  2. Open the Composer panel. Site Health tools appear under the tools drawer.

The config file lives at:

  • macOS: ~/.cursor/mcp.json
  • Windows: %USERPROFILE%\.cursor\mcp.json

If the file already has other servers, add site-health as a sibling key inside the existing mcpServers object — don't nest or duplicate.

Windsurf​

Windsurf's MCP config shape matches Cursor's exactly.

  1. Settings → Cascade → MCP Servers → Edit config.
  2. Paste the same JSON block as above.
  3. Save. Windsurf reloads servers on file change.

The config file lives at ~/.codeium/windsurf/mcp_config.json on macOS and %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows.

Verify​

In either client, ask in chat: "List my Site Health sites." You should see a call to list_sites and a result list.

Example prompts​

  • "Pull the latest scan for studio-brava and surface the top 3 opportunities."
  • "What third-party scripts are slowing down my sites?"
  • "Generate a client report for the last scan of studio-brava."

See Claude Desktop for the full prompt list — the tool surface is identical.

Why API key and not OAuth?​

Cursor and Windsurf do not yet implement the OAuth Dynamic Client Registration flow required by MCP's auth spec. Once they ship support, you'll be able to use the same connector URL as Claude.ai and skip the API key entirely. Until then, a Site Health API key is the only option.

Troubleshooting​

Server doesn't load on save. The JSON is almost certainly invalid — a trailing comma, a missing quote, or smart quotes from a word processor. Validate with https://jsonlint.com or open the config in Cursor itself (syntax errors will be highlighted).

Tools appear but all calls 401. Check the Authorization header value. It must be Bearer <key> with exactly one space. No "Bearer: " with a colon, no surrounding quotes inside the string, no newlines in the key.

"Invalid API key" even though the key is fresh. The key may have been revoked (check Settings → API Keys in Site Health) or you pasted a different user's key. Generate a new one on your account.

Tools time out. Cursor's MCP transport has a short timeout on cold starts. Retry the prompt once — subsequent calls reuse the warm connection. If timeouts persist, the MCP server may be under load; the URL https://sitehealth.octagramlabs.com/api/mcp should return a 401 instantly when opened in a browser (401 = reachable, timeout = network issue on your side).

Other MCP clients. Any client that implements MCP over HTTP with a bearer header works. Point it at https://sitehealth.octagramlabs.com/api/mcp with Authorization: Bearer <your-api-key>. Transport is HTTP only — no stdio.