Connect an MCP client - Spotlight Docs

Before you connect

Enable the API in Settings → API and copy your API key.
Open Settings → MCP and note your MCP endpoint (default: https://app.get-spotlight.com/api/mcp).
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

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

Option B: Manual config

{
  "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.

In Cursor, ask the agent to “list my Spotlight brands” as a quick connectivity test.

Claude Desktop

Claude Desktop supports custom MCP connectors over HTTP.

Open Claude Desktop and add a custom connector.
Set the connector name to Spotlight.
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:

https://app.get-spotlight.com/api/mcp?api_key=YOUR_API_KEY

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

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.

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:

Call get_organization_context — confirms auth and returns plan/brand count.
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.

​Before you connect

​Cursor

​Option A: Copy from the app

​Option B: Manual config

​Claude Desktop

​Other MCP clients

​Verify the connection

​Troubleshooting

​Security notes

Before you connect

Cursor

Option A: Copy from the app

Option B: Manual config

Claude Desktop

Other MCP clients

Verify the connection

Troubleshooting

Security notes