---
name: badgerlytics-mcp-setup
description: Connect the Badgerlytics Reports and Management MCP servers to the user's AI tool (Cursor, Claude Code, Codex, opencode or a desktop assistant) without handling their API key. Use when the user wants to set up, fix or check their Badgerlytics MCP connection.
---

# Badgerlytics MCP setup

Goal: add both servers to the user's tool so that the API key comes from the `BADGERLYTICS_API_KEY` environment variable, and never appears in chat or in shared files.

- Reports (read-only): `https://api.badgerlytics.com/mcp/reports` — needs a key with the **Reports (MCP)** scope
- Management (makes changes): `https://api.badgerlytics.com/mcp/management` — needs a key with the **Management (MCP)** scope
- Auth header: `Authorization: Bearer <API key>`

## Hard rules

- **Never ask for, accept, echo or store the API key yourself.** If the user pastes one into chat, tell them to deactivate it in Badgerlytics (Settings → API Keys) and create a new one, because chat history isn't a safe place for secrets.
- The user creates the key themselves in **Settings → API Keys** (admin or owner, Pro plan or above). Tell them to tick the scopes they want: **Reports (MCP)** for read-only access, and **Management (MCP)** only if the assistant should be allowed to change their settings. Scopes are fixed once the key exists.
- The user adds the variable to their own shell profile. Give them the line to add, with a placeholder:

  ```bash
  export BADGERLYTICS_API_KEY="sk_your_key_here"
  ```

  Then they open a new terminal and restart the AI tool.

## Per tool

Merge into existing config files. Never overwrite other servers.

**Cursor**: `~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project):

```json
{
  "mcpServers": {
    "badgerlytics-reports": {
      "url": "https://api.badgerlytics.com/mcp/reports",
      "headers": { "Authorization": "Bearer ${env:BADGERLYTICS_API_KEY}" }
    },
    "badgerlytics-management": {
      "url": "https://api.badgerlytics.com/mcp/management",
      "headers": { "Authorization": "Bearer ${env:BADGERLYTICS_API_KEY}" }
    }
  }
}
```

**Claude Code**: run in a terminal where the variable is set:

```bash
claude mcp add --scope user --transport http badgerlytics-reports https://api.badgerlytics.com/mcp/reports --header "Authorization: Bearer $BADGERLYTICS_API_KEY"
claude mcp add --scope user --transport http badgerlytics-management https://api.badgerlytics.com/mcp/management --header "Authorization: Bearer $BADGERLYTICS_API_KEY"
```

Note: `--scope user` stores the resolved header in the user's Claude Code settings. For a team-shared project config, use `.mcp.json` with `"type": "http"` and `"Authorization": "Bearer ${BADGERLYTICS_API_KEY}"`.

**Codex**: `~/.codex/config.toml`:

```toml
[mcp_servers.badgerlytics-reports]
url = "https://api.badgerlytics.com/mcp/reports"
bearer_token_env_var = "BADGERLYTICS_API_KEY"

[mcp_servers.badgerlytics-management]
url = "https://api.badgerlytics.com/mcp/management"
bearer_token_env_var = "BADGERLYTICS_API_KEY"
```

**opencode**: `opencode.json`:

```json
{
  "mcp": {
    "badgerlytics-reports": {
      "type": "remote",
      "url": "https://api.badgerlytics.com/mcp/reports",
      "headers": { "Authorization": "Bearer {env:BADGERLYTICS_API_KEY}" }
    },
    "badgerlytics-management": {
      "type": "remote",
      "url": "https://api.badgerlytics.com/mcp/management",
      "headers": { "Authorization": "Bearer {env:BADGERLYTICS_API_KEY}" }
    }
  }
}
```

**Desktop assistants that only run local servers**: point the user to https://badgerlytics.com/docs#mcp-other-tools for the bridge config. The user puts their key into that file themselves.

## Verify

1. Ask the user to restart the tool and enable both servers.
2. Call `whoami` on `badgerlytics-reports`. It should return the organization name and ID.
3. If it fails:
   - Invalid or missing key: the variable isn't visible to the tool. Check the profile, open a new terminal, and restart the tool from it.
   - The key isn't allowed on this server: it was created without that server's scope. The user creates a new key with the right scopes ticked and deactivates the old one.
   - The plan doesn't include MCP: Pro or above is required.
4. Tell the user setup is done and suggest the `badgerlytics-reports` and `badgerlytics-management` skills: https://badgerlytics.com/docs#mcp-skills.