MCP

Spotlight exposes its admin surface as a Model Context Protocol server, so AI agents (Claude Desktop, Claude Code, Cursor, ChatGPT with MCP, anything else that speaks MCP) can list, create, update, publish, and archive tours without bespoke per-host glue.

Two ways to use it:

• Remote — https://mcp.spotlight.help/mcp. OAuth (Dynamic Client Registration) for auth. Works from any device the user is signed into their MCP host on; no install. This is the recommended path.
• Local stdio — spotlight-mcp console script bundled with the backend Python package. Useful for dev / when an MCP host doesn't support remote OAuth connectors yet.

Connecting Claude Desktop (recommended)

1. Open Claude Desktop → Settings → Connectors → Add custom connector.
2. Server URL: https://mcp.spotlight.help/mcp. Hit Connect.
3. A browser tab opens to dashboard.spotlight.help/oauth/authorize. Sign in with Clerk if you're not already.
4. The consent screen asks which tenant + project this integration is allowed to operate on. Pick them and click Allow.
5. The browser bounces back to Claude Desktop's local callback ("Couldn't connect" briefly may show — that's just Claude Desktop intercepting the redirect). Claude Desktop swaps to Connected with the tool list visible.

Behind the scenes Spotlight mints a real sk_live_* API key for the chosen project and hands it back as the OAuth access token. The token IS the API key, so:

• Revoking the integration = revoke the API key in Projects → <project> → API Keys. The MCP host loses access on its next call.
• Audit log shows the same key prefix the integration uses, so you can trace which connector did what.

Connected-app keys are named mcp:<clerk-user-id>:<client-id>. If you see one of those on the API Keys page, it came from an OAuth-registered MCP host, not from manual minting.

Connecting via local stdio

cd backend
uv pip install -e "."

The mcp package ships as a core dependency now — no opt-in extra needed. (Earlier drafts of this page documented [mcp]; ignore that, the install fails with "extra mcp not provided".)

Then in your MCP host config (~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop, similar for others):

{
  "mcpServers": {
    "spotlight": {
      "command": "spotlight-mcp",
      "env": {
        "SPOTLIGHT_BASE_URL": "https://api.spotlight.help",
        "SPOTLIGHT_API_KEY": "sk_live_..."
      }
    }
  }
}

SPOTLIGHT_API_KEY is a project-scoped key minted manually from Projects → <project> → API Keys. No OAuth flow — the agent uses the key directly.

Tools

Tours — scope tours:read / tours:write

Tool	Args	Returns
list_tours	—	Array of tour summaries
get_tour	tour_id	Full tour incl. steps + triggers
create_tour	title, description?, steps?, trigger?	New tour, draft status
update_tour	tour_id, optional title/description/steps/trigger	Updated tour
publish_tour	tour_id	Tour, now published
archive_tour	tour_id	Tour, now archived

Content (banners, modals, hotspots, spotlights, tooltips, checklists) — scope content:read / content:write

Tool	Args	Returns
list_content	content_type? (filter)	Array of content summaries
get_content	content_id	Full content body
create_content	content_type, name, body	New content item, draft status
update_content	content_id, patch	Updated content
publish_content	content_id	Content, now published
archive_content	content_id	Content, now archived

content_type is one of banner, modal, hotspot, spotlight, tooltip, checklist. The wire format is unified under POST /v1/admin/content with the type as a discriminator field, which is why a single set of tools covers all six.

Themes — scope themes:read / themes:write

Tool	Args	Returns
list_themes	—	Array of themes
get_theme	theme_id	Full theme tokens
create_theme	name, tokens?	New theme
update_theme	theme_id, patch	Updated theme
set_default_theme	theme_id	The new default
delete_theme	theme_id	{deleted: true}

tokens on create_theme is a CSS-custom-property map, e.g. {"--spot-bg": "#15151d", "--spot-primary": "#ff6a4d"}. Omit it to seed with the default Indigo palette and tweak via update_theme. delete_theme refuses to delete the current default (set another theme as default first) and shared built-in themes (read-only).

Pinpoint help inbox — scope pinpoint:read / pinpoint:write

Tool	Args	Returns
list_help_requests	status_filter?, project_id?	Inbox with unread count
get_help_request	request_id	Thread + replies
reply_help_request	request_id, body, attachments?	Updated thread
set_help_request_status	request_id, new_status (open / awaiting_user / resolved)	Updated thread

Projects — scope projects:read

Tool	Args	Returns
list_projects	—	Projects visible to this token

Tool descriptions are written for agent consumption. When unsure of a payload shape, agents are told to call get_* on an existing record of the same kind to see a real example.

Scopes

OAuth-issued tokens carry an explicit scope list — picked at consent time on the dashboard's authorize page. Scope names follow <resource>:<action>:

Scope	What it grants
tours:read	list_tours, get_tour
tours:write	create / update / publish / archive / copy
content:read	list_content, get_content (banners, modals, hotspots, spotlights, tooltips, checklists)
content:write	create / update / publish / archive
themes:read	list_themes, get_theme
themes:write	create / update / set-default
pinpoint:read	help-inbox list + read
pinpoint:write	reply + set-status
projects:read	list_projects (discovery)
admin:write	Reserved for high-trust administrative actions. Implicit superset of every other scope.

Mutating tools return a missing_scope error naming the required scope, so an agent can ask the user to re-authorise with the right one. Dashboard-minted (non-OAuth) keys carry no explicit scope list and behave as full-access — preserving the historic "one key, full power" behaviour for server-side use.

Errors

Each tool returns either the API's response payload (success) or a structured error:

{
  "error": "spotlight_api_error",
  "status_code": 422,
  "request_id": "req_abc123",
  "detail": "{...full body...}"
}

request_id is what to grep CloudWatch with when something unexpected happens.