> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP client

> Set up Cursor, Claude Desktop, and other MCP clients to talk to Spotlight.

## Before you connect

1. Enable the API in **Settings → API** and copy your API key.
2. Open **Settings → MCP** and note your **MCP endpoint** (default: `https://app.get-spotlight.com/api/mcp`).
3. Keep your API key secret — treat it like a password.

All MCP clients authenticate with the **`x-spotlight-api-key`** header, using the same key as REST API requests.

## Cursor

Cursor supports remote MCP servers over HTTP. Add Spotlight to your MCP configuration file.

### Option A: Copy from the app

1. In Spotlight, go to **Settings → MCP**.
2. Under **Cursor MCP Config**, click the copy button.
3. Paste the JSON into your Cursor MCP config (project `.cursor/mcp.json` or global settings, depending on your setup).
4. Replace `YOUR_API_KEY` with your real API key if the placeholder is still shown.

### Option B: Manual config

```json theme={null}
{
  "mcpServers": {
    "spotlight": {
      "url": "https://app.get-spotlight.com/api/mcp",
      "headers": {
        "x-spotlight-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

After saving, restart Cursor or reload MCP servers. You should see **spotlight** listed with tools such as `list_brands` and `get_organization_context`.

<Tip>
  In Cursor, ask the agent to "list my Spotlight brands" as a quick connectivity test.
</Tip>

## Claude Desktop

Claude Desktop supports custom MCP connectors over HTTP.

1. Open Claude Desktop and add a **custom connector**.
2. Set the connector name to **Spotlight**.
3. For the server URL, use the value from **Settings → MCP → Claude Desktop Connector** in the Spotlight app. It includes your API key as a query parameter:

```text theme={null}
https://app.get-spotlight.com/api/mcp?api_key=YOUR_API_KEY
```

4. Leave **OAuth Client ID** and **Client Secret** empty.
5. Save and enable the connector.

<Warning>
  The Claude connector URL embeds your API key in the query string. Only use it on trusted machines and do not share screenshots of the full URL.
</Warning>

## Other MCP clients

Any client that supports **HTTP MCP** with custom headers can connect using:

| Setting         | Value                                   |
| --------------- | --------------------------------------- |
| **URL**         | `https://app.get-spotlight.com/api/mcp` |
| **Auth header** | `x-spotlight-api-key: YOUR_API_KEY`     |
| **Transport**   | HTTP                                    |

Alternative header names accepted by the underlying API (if your client cannot set `x-spotlight-api-key`):

| Header              | Example                              |
| ------------------- | ------------------------------------ |
| `x-api-key`         | `x-api-key: YOUR_API_KEY`            |
| `spotlight-api-key` | `spotlight-api-key: YOUR_API_KEY`    |
| `Authorization`     | `Authorization: Bearer YOUR_API_KEY` |

## Verify the connection

Once connected, ask your assistant to:

1. Call **`get_organization_context`** — confirms auth and returns plan/brand count.
2. Call **`list_brands`** — returns brand IDs for your organization.

If authentication fails, you'll see an error such as `Missing Spotlight API key` or `Invalid API key`. Double-check the key in **Settings → API** and that API access is enabled.

## Troubleshooting

| Symptom                 | Likely cause                        | Fix                                                     |
| ----------------------- | ----------------------------------- | ------------------------------------------------------- |
| No MCP tab in Settings  | API access not enabled for your org | Enable API in **Settings → API** or request beta access |
| `401 Invalid API key`   | Wrong or revoked key                | Copy the current key from **Settings → API**            |
| `429 Too Many Requests` | Rate limit exceeded                 | Wait and retry; default quota is 120 requests/minute    |
| Tools not appearing     | Client not reloaded                 | Restart the MCP client after config changes             |
| Empty brand list        | Wrong organization selected         | Confirm the API key belongs to the intended org         |

## Security notes

* API keys are scoped to a **single organization**.
* Keys inherit the same permissions as your Spotlight account (e.g. viewers cannot modify data via API or MCP).
* Rotate keys from **Settings → API** if a key may have been exposed.