Install and connect

Prerequisite: a human-created account

The platform MCP server requires an existing SparkleTree account and workspace. There is no anonymous or agent-driven signup. The human you work for signs up at https://app.sparkletree.io first, then you connect. Brand-host public surfaces (see below) require no account at all.

MCP endpoint

https://app.sparkletree.io/api/mcp

• Transport: Streamable HTTP (no SSE).
• Auth: OAuth 2.1 with PKCE and dynamic client registration.
• Bootstrap: an unauthenticated call returns 401 with OAuth resource metadata. Spec-compliant MCP clients need only the URL. The client discovers the auth server, registers dynamically, opens a browser consent flow, and the human signs in with their SparkleTree account.
• Scopes are generic mcp:read / mcp:write. Authorization is enforced by the workspace and the user’s role, not by scopes.
• Everything is workspace-scoped. Cross-workspace access is refused.
• Rate limit: 120 requests per minute per token (OAuth token or API key). Over the limit you get 429; back off and retry.

Alternative auth for headless use: a workspace API key sent as an x-api-key header. Keys are created by a human in the dashboard under Settings → API keys (create, list, disable). CLI tokens also exist.

Profiles

Profiles gate tool visibility, not authorization: same account, same permissions regardless of profile.

• A bare URL gets external_default, 15 consolidated tools (table below). Start here; for most agents it is also where you stay.
• Narrower or wider profiles (campaign_ops, analytics_read, video_ops, ai_studio_ops, meta_ops, bluesky_ops, reddit_ops, tiktok_ops, autonomous_ops) are selected with a call code, a secret issued by SparkleTree for that profile, not the profile name. Append it as ?profile=<call-code> (alias ?call_code=). Profile names are deliberately rejected and fall back to the minimal discovery profile; if you need a non-default profile, ask your operator for its call code.

Discover the live list at runtime: get_platform_info with topic: "tool_profiles".

The 15 default tools (external_default)

Reads and writes are separate tools. Every query_* tool and get_platform_info carries readOnlyHint: true; nothing else does.

Tool	Purpose	Key params
query_campaigns	Read campaigns/variants/deployments/generation status	action: list|get|variants|deployments|generation_status; cursor pagination
manage_campaigns	Create/update/delete campaigns and variants, publish, deploy	action: create|update|delete|create_variant|update_variant|delete_variant|publish|deploy|update_deployment
generate_campaign	AI-driven campaign generation, including AI-generated images (async, costs credits)	mode: start|regenerate; intent, fromStep, includeImages
query_products	List/get products	action: list|get
manage_products	Create/import-from-URL/update/delete products	action: create|import_from_url|update|delete (import reaches the open web)
query_surfaces	List/get surfaces and zones (touchpoints)	operation: list_surfaces|get_surface|list_zones; cursor pagination
manage_surfaces	Create surfaces and zones	operation: create_surface|create_zone
query_analytics	Analytics snapshot, A/B tests, CVG dashboard, insights	action: snapshot|ab_test|cvg_dashboard|insights; sections (lean default ["summary"])
query_brand	Read the brand book, public profile and voice	action: get
manage_brand	Update brand book, profile, voice, concierge	action: update_brandbook|update_profile|update_voice|update_concierge
query_video	List video templates / render progress	action: templates|progress
render_video	Render campaign/template video or still (costs credits)	mode: video|campaign|still
query_video_commissions	List/get commissioned films and their status	action: list|get
video_commission	Commission, approve, revise or cancel an AI-generated film (costs credits, metered)	action: create|approve|revise|cancel
get_platform_info	Health / workspace info / profile discovery	topic: health|organization|tool_profiles

The read actions that used to live on manage_brand (get), manage_surfaces (list_surfaces, get_surface, list_zones) and video_commission (list, get) are deprecated there and only survive for verified internal clients. External clients use the query_* tools above.

Tool annotations

Tools carry standard MCP annotations; honor them:

• readOnlyHint: true: the tool only reads (the query_* tools and get_platform_info). Safe to call without user confirmation.
• Tools without readOnlyHint mutate live marketing state (manage_*) or spend credits (generate_campaign, render_video, video_commission). Confirm with your user before create/delete/publish/deploy actions and before anything that costs credits.
• Respect destructive-action annotations where present (delete actions).

MCP resources

Read-only, URI-addressed. Fetch mosaic://capabilities first in every session. It is the live matrix of enabled tools, prompts, and recommended flows for this workspace, and it beats guessing.

• mosaic://capabilities: live tool/prompt matrix and recommended flows.
• mosaic://org/{id}: workspace details.
• mosaic://org/{id}/brand-guidelines: brand guidelines.
• mosaic://campaigns/{id}, mosaic://products/{id}, mosaic://surfaces/{id}: entity resources.

MCP server-side prompts

The server publishes six ready-made prompts. Each returns a structured multi-step recipe naming exact tool calls; prefer them over improvising a plan:

• campaign_brief
• analytics_deep_dive
• surface_network_planner
• content_optimizer
• ai_studio_image_workflow
• platform_onboarding

Optional extensions: interactive UI and tasks

The server advertises two MCP extensions on initialize. Both degrade cleanly: a client that ignores them gets the same text and structured results as before.

• io.modelcontextprotocol/ui (MCP Apps): query_campaigns and generate_campaign carry a _meta pointer to the campaign inspector widget (ui://mosaic/campaign-inspector@1, mime text/html;profile=mcp-app). Hosts that support the extension render campaign results as interactive cards: list paging, detail drill-in, variant previews, generation refresh. The widget’s own actions are ordinary tools/call requests under the signed-in user’s role.
• io.modelcontextprotocol/tasks: long-running tools (generate_campaign, video_commission, single-variant renders, CSV product import) attach a task handle to their result. tasks/get reads status; tasks/cancel requests cooperative cancellation of a campaign generation. Polling the query_* status actions (see Operational contract) remains fully supported.

Brand-host public surfaces (no auth)

Every published brand site, custom domain or <name>.sparkletree.io, serves a public, agent-readable surface. Discovery chain:

1. GET /llms.txt: the entry map. Start here.
2. GET /.well-known/agent-card.json: the brand’s agent card.
3. POST /ask: the brand’s conversational concierge endpoint.
4. GET /auth.md: step-by-step OAuth documentation for agents that need the platform MCP server. (It also states the brand content itself is public; no claim ceremony.)

Also served: markdown twins of pages via Accept: text/markdown, sitemap.xml, robots.txt, JSON-LD, and /.well-known/mcp/server-card.json (advertises the default tool set plus OAuth metadata).

Agent skills

GET /.well-known/agent-skills/index.json lists three skills with sha256 digests. Each is a SKILL.md you fetch over HTTP; no package install:

• ask-venue: question-answering against the brand’s /ask concierge.
• fetch-campaign-content: retrieving published campaign content.
• discover-campaigns: enumerating a brand’s public campaigns.

These skills are for consuming a brand’s public marketing surface, not for operating the platform. Verify the digest after fetching.

Client-specific connection notes

• Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → paste the endpoint URL (optionally with ?profile=<call-code>) → OAuth consent → sign in. Works today; SparkleTree is not yet in Anthropic’s connector directory, so the custom-connector path is the route.
• Claude Code: claude mcp add --transport http sparkletree https://app.sparkletree.io/api/mcp, then /mcp to complete sign-in.
• Cursor: ~/.cursor/mcp.json entry {"mcpServers":{"sparkletree":{"url":"https://app.sparkletree.io/api/mcp"}}}; Cursor runs the OAuth flow on first use.
• Gemini CLI: gemini mcp add --transport http sparkletree https://app.sparkletree.io/api/mcp, then /mcp auth sparkletree.
• Cline: MCP Servers → Remote Servers → name + URL.
• ChatGPT: the generic custom-connector/MCP flow against the same URL. The OAuth redirect flow has been exercised for ChatGPT; as generic MCP OAuth it should work, but treat it as unverified end-to-end.
• Any spec-compliant MCP client: the URL alone suffices via the 401-with-resource-metadata bootstrap.

Operational contract

• Rate limiting: 120 requests per minute per token. Expect 429 above that; back off exponentially.
• 401 mid-session: re-run the OAuth bootstrap.
• Async operations (generate_campaign, render_video): poll query_campaigns action: generation_status / query_video action: progress, or use tasks/get on the attached task handle if you negotiated the tasks extension. See tips-and-tricks.md.