setting-up-coredash

name	setting-up-coredash
description	Use when setting up the CoreDash MCP server for Core Web Vitals diagnosis — "how do I connect CoreDash", "set up CoreDash", "connect CoreDash with OAuth / browser login", "get a CoreDash API key", "CoreDash isn't connected", or when the cwv-superpower orchestrator has no CoreDash connection and the user wants to connect. Walks through client detection, account setup, keyless OAuth (browser login) or API-key authentication, and per-client MCP configuration.
version	2.2.0
allowed-tools	Read, Write, Edit, Glob, Grep

Setting Up CoreDash

Invocation

Called by the cwv-superpower orchestrator when CoreDash is unavailable and the user wants to connect, or invoked directly when the user asks how to set up CoreDash MCP.

Do not skip steps. Walk the user through each step and wait for confirmation before moving to the next.

---

Step 1: Detect the MCP client

Ask the user which tool they are working in:

"Which AI coding tool are you using?"

• Claude Desktop
• Claude Code (terminal)
• Cursor
• Windsurf
• Gemini CLI
• Other

Store the answer for Step 4.

---

Step 2: Check for a CoreDash account

Ask the user:

"Do you have a CoreDash account at app.coredash.app?"

• If yes: proceed to Step 3.
• If no: say the following and wait:

"You'll need a free CoreDash account first. Go to https://coredash.app/signup and create one. It takes about two minutes. Come back here when you're in."

---

Step 3: Choose a connection method

CoreDash MCP accepts two authentication methods. Pick based on the client and use case:

Method	Best for	API key needed?
Browser login (OAuth)	Interactive use in native/CLI clients like Claude Code (terminal)	No
API key (cdk_…)	Headless / automated / CI, agency or multi-project setups (master keys), and config-file clients (Claude Desktop, Cursor, Windsurf, Gemini CLI)	Yes

Both connect to the same hosted server — nothing changes on the CoreDash side. OAuth is the better experience for interactive clients; API keys are the right choice when there's no interactive browser.

• If the user is on Claude Code (terminal) and wants the simplest path → use Option A (Browser login) in Step 4.
• For headless/CI use, multi-project agency setups, or any config-file client → use Option B (API key) in Step 4.

---

Step 4: Connect

Option A — Browser login (OAuth), recommended for Claude Code

No API key required. Add the server with no header:

claude mcp add --transport http coredash https://app.coredash.app/api/mcp

Then authenticate from inside an interactive Claude Code session:

1. Run /mcp
2. Select coredash
3. Choose Authenticate
4. Your browser opens the CoreDash login/consent page — log in, pick the project to connect, and approve.

Claude Code stores a short-lived OAuth token that auto-refreshes (1-hour access token, 30-day refresh token) and is revocable from CoreDash at any time.

Note: OAuth is triggered interactively through /mcp → Authenticate, not by claude mcp list. claude mcp list is only a health check — it will report the server as failing ("tools fetch failed") until you authenticate. That's expected; complete the /mcp flow above and it connects.

Once authenticated, skip to Step 5 to verify.

---

Option B — API key

First, generate the key. Tell the user:

"Let's generate an API key. Inside the CoreDash app:

1. Open the project you want to connect
2. Go to Project Settings
3. Click the API Keys (MCP) tab
4. Give the key a name (e.g. 'Claude Code' or 'Cursor')
5. Click Generate API Key
6. Copy the key now — it starts with cdk_ and is shown exactly once"

Ask: "Do you have your API key copied?" Wait for confirmation, then provide the exact config for the tool the user chose in Step 1.

Claude Code (terminal)

Run this command, replacing the key:

claude mcp add --transport http coredash https://app.coredash.app/api/mcp \
  --header "Authorization: Bearer cdk_YOUR_API_KEY"

Tip: for interactive Claude Code use, Option A (browser login) is simpler and needs no key. Use this API-key command for headless or scripted setups.

Claude Desktop

Open this file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this inside the mcpServers object (create the file if it does not exist):

{
  "mcpServers": {
    "coredash": {
      "url": "https://app.coredash.app/api/mcp",
      "headers": {
        "Authorization": "Bearer cdk_YOUR_API_KEY"
      }
    }
  }
}

Replace cdk_YOUR_API_KEY with the key they copied. Then restart Claude Desktop.

Cursor

Open Settings → MCP → Add Server. Set:

• Name: coredash
• Type: HTTP
• URL: https://app.coredash.app/api/mcp
• Header: Authorization: Bearer cdk_YOUR_API_KEY

Windsurf

Open Settings → AI → MCP Servers → Add. Set:

• Name: coredash
• Type: HTTP
• URL: https://app.coredash.app/api/mcp
• Header: Authorization: Bearer cdk_YOUR_API_KEY

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "coredash": {
      "url": "https://app.coredash.app/api/mcp",
      "headers": {
        "Authorization": "Bearer cdk_YOUR_API_KEY"
      }
    }
  }
}

Other MCP clients

Tell the user:

"Any MCP-compatible client needs two things:

• Endpoint URL: https://app.coredash.app/api/mcp
• Header: Authorization: Bearer cdk_YOUR_API_KEY

Check your client's documentation for how to add an HTTP MCP server with a custom header."

---

Step 5: Verify the connection

Once the user confirms they've connected — authenticated via /mcp (Option A) or saved the config and restarted their client (Option B) — silently call get_metrics with no arguments. Do not announce the test beforehand.

• If it returns data (LCP, INP, CLS, FCP, TTFB values): say

"Connected. CoreDash MCP is live — I can now see your real Core Web Vitals data."

Then tell the user which skill they were trying to run originally and offer to continue with it.

• If it returns -32001 Authentication Error or the user hasn't authenticated yet:

  • Option A (OAuth): say

    "You still need to authorize. Run /mcp, select coredash, and choose Authenticate — your browser will open the CoreDash login. Note that claude mcp list shows the server as failing until you do this; that health check doesn't trigger the login."

  • Option B (API key): say

    "The API key looks wrong. Check that it starts with cdk_, there are no extra spaces, and the Bearer prefix is included. If the key was lost, generate a new one from Project Settings."

• If the tool is not found or unavailable: say

"The MCP server isn't loading yet. Try fully quitting and restarting your AI client (not just reloading). If you're on Claude Code, run claude mcp list to confirm the server appears — then, for OAuth, run /mcp → Authenticate to log in."

---

Notes (share only if the user asks)

• OAuth (browser login): the token is scoped to the project you pick during consent and auto-refreshes (1-hour access token, 30-day refresh token). Re-run /mcp → Authenticate to switch projects or after revoking. Nothing needs to be configured on the CoreDash side — the keyless flow just works on the hosted server.
• API key: each key is scoped to one project. If you have multiple sites, generate a separate key per project. For agency/multi-project automation, use a master key.
• Don't set any environment variable for either method — it isn't part of the connection flow.
• The MCP server is read-only. It cannot modify your site or your CoreDash data.
• To revoke access: for an API key, go to Project Settings → API Keys (MCP) and click Revoke; for OAuth, revoke the authorized connection from your CoreDash account.
• Rate limits per plan (reset at midnight UTC):

Plan	Daily MCP requests
Trial	30
Starter	100
Standard	500
Pro	1,000
Enterprise	50,000