Skip to main content

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.

​
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

{
  "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.
  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:
https://app.get-spotlight.com/api/mcp?api_key=YOUR_API_KEY
  1. Leave OAuth Client ID and Client Secret empty.
  2. 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:
SettingValue
URLhttps://app.get-spotlight.com/api/mcp
Auth headerx-spotlight-api-key: YOUR_API_KEY
TransportHTTP
Alternative header names accepted by the underlying API (if your client cannot set x-spotlight-api-key):
HeaderExample
x-api-keyx-api-key: YOUR_API_KEY
spotlight-api-keyspotlight-api-key: YOUR_API_KEY
AuthorizationAuthorization: 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

SymptomLikely causeFix
No MCP tab in SettingsAPI access not enabled for your orgEnable API in Settings → API or request beta access
401 Invalid API keyWrong or revoked keyCopy the current key from Settings → API
429 Too Many RequestsRate limit exceededWait and retry; default quota is 120 requests/minute
Tools not appearingClient not reloadedRestart the MCP client after config changes
Empty brand listWrong organization selectedConfirm 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.