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 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. Two manage_campaigns actions change no campaign data but are not free: check_component stores a design check and runs a browser check in a sandbox (sandbox minutes, a daily limit per workspace), and match_templates can make a model call (cached; uncached calls have a daily limit per workspace). Earlier server versions had these two actions on query_campaigns; a call that still sends them there gets an invalid_input error that names manage_campaigns.

Tool	Purpose	Key params
query_campaigns	Read campaigns, variants, deployments, generation status, share links, DOOH status, the campaign manifest, the campaign’s custom Squid designs, and the predicted response rate of each variant; browse the Squid template library	action: list|get|variants|deployments|generation_status|share_links|dooh_status|dooh_analytics|manifest|get_component|forecast|list_templates|get_template; cursor pagination
manage_campaigns	Create/update/delete campaigns and variants, publish, deploy, duplicate, share links, and custom Squid designs; check a custom design; match templates to a campaign and apply one	action: create|update|delete|create_variant|update_variant|delete_variant|publish|deploy|update_deployment|duplicate|create_share_link|revoke_share_link|generate_playbook|create_component|publish_component|revert_component|check_component|match_templates|apply_template
generate_campaign	AI-driven campaign generation, including AI-generated images (async; counts against the campaign generation quota; with images on, reserves image credits before the run is accepted)	mode: start|regenerate; intent, fromStep, includeImages
query_products	List/get products, check CSV import jobs	action: list|get|import_status
manage_products	Create/import/update/delete products and manage their images	action: create|import_from_url|update|delete|import_csv|add_image|remove_image|set_primary_image|reorder_images (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, export. Impressions, clicks and conversions include Meta Ads on day-based ranges. Section creatives gives figures per creative and per channel (Signage, Web, Brand pages, Socials with Meta under it, QR scans), each with its source, per-channel rates and rows not linked to a creative; summary.meta (Meta part and Meta reach) is still returned	action: snapshot|ab_test|cvg_dashboard|insights|export; sections (lean default ["summary"])
query_brand	Read the brand book, public profile and voice, and the brand host home page (one version’s html, or one file with path, with pageId); list a version’s files; check a page or a whole version against the rules	action: get|get_page|get_site|check_page
manage_brand	Update brand book, profile, voice, concierge and logo (admin); write drafts of the brand host home page and add more pages and files to a version (member); run a render check of a version (member, sandbox minutes); publish, revert or delete versions (admin)	action: update_brandbook|update_profile|update_voice|update_concierge|set_logo|create_page|edit_page|create_version|put_files|create_file_upload|delete_files|publish_page|revert_page|delete_page|render_check
query_video	List video templates, render progress, stored campaign renders	action: templates|progress|renders
render_video	Render campaign/template video or still (within daily per-workspace render limits); record a variant’s custom Squid design as MP4s for ads	mode: video|campaign|still|squid
upload_asset	Store an image or video file in the workspace and get an assetId	action: from_url|from_data|create_upload|complete_upload (from_url reaches the open web)
query_assets	List/get files stored in the workspace	action: list|get
get_platform_info	Health / workspace info / profile discovery	topic: health|organization|tool_profiles

render_video mode: squid needs a published custom design on the variant and a paid plan: workspaces on the Starter plan or without an active plan get a forbidden error. The recording runs in a sandbox, not on the render service the other modes use, is limited per workspace per day, and returns a precondition_failed error (“Video export is turned off on this server”) while video export is switched off. Polling uses query_video action: progress with the same campaignId and variantId.

generate_campaign with images on (the default) sets the image credits for every image the run will make aside before the run is accepted. If the workspace has too few, the call returns precondition_failed and nothing is created. includeImages: false uses no image credits.

Adding images and video

upload_asset is the way to put a file into the workspace. The returned assetId is accepted by manage_products (imageAssetId, add_image), manage_brand set_logo, and image or video fields in a variant’s contentStructure.

• from_url: SparkleTree downloads a public link and stores its own copy.
• from_data: a small file sent inline as base64 (at most 1 MB).
• create_upload then complete_upload: for a local or large file (images up to 16 MB, video up to 128 MB). create_upload (with filename and the exact size in bytes) returns an uploadUrl, the headers to send, an uploadId and a ready-made curl line. Send the file with an HTTP PUT to uploadUrl as multipart/form-data, with the file in the form field file and the returned headers, not as the raw request body. The curl line does this once you replace <path to the file>. When the PUT has finished, call complete_upload with the uploadId. The file is checked before the assetId can be used.

Product image links passed to manage_products (imageUrl) are also copied into workspace storage rather than linked.

Custom Squid designs

A campaign can carry custom designs for its Squid: each one is a complete HTML document plus a manifest, written by you. Read query_campaigns action: get_component first and follow the agentGuide it returns. manage_campaigns action: create_component saves a draft and returns a previewUrl (member role). manage_campaigns action: check_component checks a stored design: static findings at once, and a browser check at five sizes with screenshots that finishes in a minute or two (member role; warnings only). publish_component adds the design to the campaign as a new variant in its rotation, and revert_component pauses the variant or variants carrying that design (both admin role).

The Squid template library actions (query_campaigns list_templates and get_template, and manage_campaigns match_templates and apply_template) are off unless the template library is switched on for the server; while it is off they return a not_configured error.

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

Earlier server versions also had video_commission and query_video_commissions (AI-generated films) on this profile. Since server version 1.0.5 they are not part of the external tools; films are commissioned in the SparkleTree dashboard.

Tool annotations

Tools carry standard MCP annotations; honor them:

• readOnlyHint: true: the tool changes no workspace data (the query_* tools and get_platform_info). Safe to call without user confirmation.
• Tools without readOnlyHint mutate live marketing state (manage_*), store files in the workspace (upload_asset), or start paid jobs (generate_campaign, render_video). manage_campaigns check_component and match_templates change no campaign data but use sandbox minutes or a model call within daily limits. Confirm with your user before create/delete/publish/deploy actions and before any paid job.
• 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. It lists exactly the tools your connection has, and a recommended flow only when your connection has every tool the flow names.
• mosaic://org/{id}: workspace details.
• mosaic://org/{id}/brand-guidelines: brand guidelines.
• mosaic://campaigns/{id}, mosaic://products/{id}, mosaic://surfaces/{id}: entity resources.
• mosaic://brand-page-guide: how to write the brand host home page (manage_brand create_page).
• mosaic://campaigns/{campaignId}/squid-component-guide: how to write a campaign’s custom Squid design; the same text query_campaigns action: get_component returns as agentGuide.

MCP server-side prompts

The server publishes a ready-made prompt only when your profile exposes every tool the prompt names; external_default has five. 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
• platform_onboarding

ai_studio_image_workflow is published only on profiles with the AI Studio tools (ai_studio_ops). The prompts list in mosaic://capabilities names exactly the prompts your connection has.

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@2, 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, 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.