Spotlight

Appearance

Getting Started with the MCP Connector ​

If you're here to wire Spotlight into an LLM (Claude Desktop, Cursor, ChatGPT with MCP, etc.) so it can author tours for you, this is the right page.

The setup itself is ~5 minutes; the rest of this page is the system-prompt context you should paste into your agent so it's actually useful from the first message.

1. Connect ​

In Claude Desktop:

  1. Settings → Connectors → Add custom connector.
  2. Server URL: https://mcp.spotlight.help/mcp
  3. Connect. A browser tab opens to a Spotlight consent page — sign in via Clerk (if not already), pick tenant + project the integration is allowed to operate on, click Allow.
  4. Tab redirects back to Claude Desktop's local callback (might flash "Couldn't connect" briefly — Claude's intercepting the redirect). The connector swaps to Connected with the tool list visible.

For other hosts (Cursor, Windsurf, ChatGPT) the steps are the same — add a remote MCP server pointing at https://mcp.spotlight.help/mcp and walk the OAuth dance.

Behind the scenes Spotlight mints a real sk_live_* API key, scoped to the project you picked, and hands it back as the OAuth access token. Revoking the integration = revoking that key in Projects → {project} → API Keys.

2. Drop this into the agent's system prompt ​

This is the minimum context a fresh agent needs to be productive. Paste it into Claude Desktop's "Custom instructions", Cursor's .cursorrules, or wherever your host puts system-prompt text:

markdown
You have access to a Spotlight MCP server.  Tools are grouped by
resource; each is gated by a scope on the calling token (the user
picked the scopes at consent time):

Tours — tours:read / tours:write
  list_tours / get_tour / create_tour / update_tour /
  publish_tour / archive_tour

Content — content:read / content:write
  list_content(content_type?) / get_content / create_content /
  update_content / publish_content / archive_content
  Use content_type one of: banner | modal | hotspot | spotlight |
  tooltip | checklist.

Themes — themes:read / themes:write
  list_themes / get_theme / create_theme / update_theme /
  set_default_theme / delete_theme
  create_theme(name, tokens?) — tokens is a CSS custom-property
  map like {"--spot-bg":"#15151d","--spot-primary":"#ff6a4d"}.
  Omit to seed with the default palette and tweak via update_theme.
  delete_theme refuses to drop the current default; promote
  another with set_default_theme first.

Pinpoint help inbox — pinpoint:read / pinpoint:write
  list_help_requests / get_help_request / reply_help_request /
  set_help_request_status

Projects — projects:read
  list_projects   (discovery; tells you which projects your token sees)

Conventions to follow:

1. Read before write. If you're unsure of the schema for a body
   or patch, call get_* on an existing record of the same kind
   first.  Errors are JSON with a request_id — surface it when
   you report a failure.
2. Always create drafts. create_tour and create_content return
   draft status.  Show the user what you built; only call
   publish_* after explicit approval.
3. Stable selectors when targeting DOM elements (tours, hotspots,
   spotlights, tooltips):
   - data-* attributes first ([data-spotlight="..."])
   - semantic landmark roles + aria-label
   - intentional class names (kebab-case)
   - never tag+nth-child chains or utility-class soup
4. Scope errors are explicit. A missing_scope error names the
   exact scope required; ask the user to re-authorise the
   connector with that scope.
5. Triggers: page_load, first_visit, event, idle, scroll_depth,
   delay, manual.  Audience rules + feature_flag (plain string)
   further narrow who sees a piece of content.  Default to
   page_load if unsure.
6. One project per token.  The token's scopes are bound to the
   tenant + project picked at consent.  If asked about another
   project, list_projects to confirm what's reachable, then say
   so plainly.

3. Smoke-test ​

Send the agent a one-liner and watch it work:

"List the tours I have today, then create a draft 3-step welcome tour targeting [data-spotlight='dashboard-nav'], [data-spotlight='create-button'], and the page header. Trigger on first visit to /dashboard. Don't publish."

A working agent will:

  1. Call list_tours() to see what's there.
  2. Probably call get_tour() on the first one to learn the step schema.
  3. Call create_tour(...) with a well-formed body.
  4. Hand you back the new tour's id + a summary, asking for approval before publishing.

If it goes off the rails (invents endpoints, claims tools that don't exist, edits the wrong project), the prompt above is the shortest path back.

4. Revoke / re-grant access ​

  • Inside Spotlight: Projects → {project} → API Keys → find the row named mcp:user_xxx:client_yyy (the integration named itself) → revoke.
  • Inside Claude Desktop / your host: remove + re-add the connector to mint a fresh token.

A token revoke kills the integration on its next tool call. The API Keys page is the source of truth — connector-issued keys are named mcp:<user>:<client> so they're easy to spot.

See MCP overview for the full tool reference, scope catalogue, and auth model.

Spotlight