MCP connector setup

This is the technical companion to the essentials guide, Connect your AI. Read this if you administer the workspace, hand out access to agents, or need the details behind the paste-a-URL flow.

The endpoint

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

It speaks Streamable HTTP MCP with OAuth 2.1, PKCE, and dynamic client registration. An unauthenticated call returns 401 with resource metadata, so any spec-compliant MCP client bootstraps itself: paste the URL, the browser opens a consent screen, and the user signs in with an existing SparkleTree account.

In Claude, that’s Settings → Connectors → Add custom connector → paste the URL. ChatGPT, Cursor, Gemini CLI, Cline and Claude Code point at the same endpoint through their own remote-server settings; the essentials guide lists the exact steps for each.

Note: a human needs a SparkleTree account and workspace before any agent can connect. There is no agent-driven signup, and SparkleTree is not yet listed in Anthropic’s connector directory, so the custom-connector path is the supported route today.

What connecting grants

The agent acts as the signed-in user. Same role, same workspace: an editor’s agent can edit campaigns but not change workspace settings; a viewer’s agent can only read. Every tool is workspace-scoped, and cross-workspace access is refused. There is no separate “agent permission” to configure. If you want an agent with less power, connect it under an account with a narrower role, or hand it a narrower tool profile (below).

The default tool set

A bare connector URL gets the external_default profile: 15 tools. Reads and writes are separate tools on purpose, so a client can allow every read without asking and still confirm every change.

Read tools, marked read-only:

• query_campaigns: campaigns, variants, deployments, generation status, share links, DOOH status and analytics, the campaign manifest, the predicted response rate of each variant, and the campaign’s custom Squid designs. Two of its actions cost something without changing campaign data: checking a custom design runs a browser check in a sandbox (limited per workspace per day), and matching Squid templates to a campaign can make an AI model call (also limited per day). The Squid template actions are off unless the template library is switched on.
• query_products: the product catalog and the status of CSV product imports.
• query_surfaces: surfaces and zones (the touchpoints campaigns deploy to).
• query_brand: the brand book, public profile and voice, and the brand host home page.
• query_analytics: snapshots (including figures per creative and per channel), A/B tests, the CVG dashboard, insights, and data export.
• query_video: video templates, render progress, and stored campaign renders.
• query_assets: images and video files stored in the workspace.
• get_platform_info: health, workspace info, profile discovery.

Write tools, which change live workspace state:

• manage_campaigns, manage_products, manage_surfaces, manage_brand: create, update, delete, publish, deploy. manage_brand also writes the brand host page and its files: members save drafts, admins publish, revert and delete versions and change the brand configuration.
• upload_asset: store an image or video file in the workspace, from a link or a file, so it can be used as a product image, a logo, or campaign media. SparkleTree keeps its own copy.

Tools that start paid jobs:

• generate_campaign (credits and the campaign generation quota), render_video (daily render limits).

AI-generated films are commissioned in the SparkleTree dashboard (Open Studio), not through the connector.

Agents get the same list, with parameters, in Install and connect.

Tool profiles

Other profiles exist for agents with one job: campaign_ops, analytics_read, video_ops, and the social families meta_ops, reddit_ops, tiktok_ops and bluesky_ops, among others. A profile is selected with a call code, a secret issued by SparkleTree for that profile, not by the profile’s name:

https://app.sparkletree.io/api/mcp?profile=<call-code>

A profile name in the URL is rejected and falls back to a minimal discovery profile, so an agent cannot widen its own tool list by guessing. Call codes are issued on request through support@sparkletree.io. An agent can discover the current profile list at runtime via get_platform_info with topic tool_profiles.

Profiles gate which tools the agent sees, not what the user is authorized to do; authorization always follows the signed-in user’s role. Hand out a narrower profile when an agent has one job: a weekly reporting bot gets analytics_read so it can’t touch campaigns even by accident; a social scheduler gets meta_ops and nothing else. Narrow profiles also keep the tool list small, which makes agents more reliable.

Rate limit

The endpoint allows 120 requests per minute per token, counted per OAuth token or API key. Above that, requests return 429 until the minute rolls over; well-behaved clients back off and retry. A normal assistant session stays far below the limit. A script that pages through thousands of products should pace itself.

Interactive results in the client

In clients that support MCP Apps (Claude among them), campaign results render as an interactive inspector card instead of plain text: campaign lists with status badges and paging, drill-in detail with variant preview links, and a live generation-status view with refresh. There is nothing to configure. A client that supports the extension shows the card, and any other client falls back to the normal text answer. The card’s actions run as ordinary tool calls, so they follow the connected user’s role like everything else.

API-key authentication

For scripts and agents that can’t do an OAuth browser flow, use a workspace API key instead.

1. Go to Dashboard → Settings → API keys.
2. Click create, name the key, and copy it once.
3. Send it as the x-api-key header on requests to the endpoint.

Treat keys like passwords. They carry workspace access, so store them in a secrets manager and disable them the moment their automation is retired. See Advanced settings for the Settings tour.

Tools that spend credits

generate_campaign (AI campaign generation, including AI-generated images) uses your workspace’s monthly creative credits and its campaign generation quota. Product import from URL also draws on credits. If a connected agent runs these, the credits come out of the same pool your team uses, which is worth knowing before you point an autonomous agent at them. AI images use credits by model, and with images on, generate_campaign sets aside the credits for all of the campaign’s images before the run is accepted. If the workspace can’t pay for them, nothing is generated and the tool returns a precondition_failed error whose details include httpStatus: 402, how many credits the images need, and what to do next.

render_video starts rendering jobs that count against daily limits per workspace. Recording a custom Squid design as video (render_video mode squid) needs a paid plan: workspaces on the Starter plan or without an active plan get a forbidden error. Workspaces that can go into overage pass this check. When credits run out for other generating actions, they return a quota error. Published campaigns keep serving either way. See Plans and limits for how credits and quotas work.

Revoking access

• OAuth connections: remove the connector in the client’s settings, and the agent loses access on its next call.
• API keys: disable the key in Settings → API keys. Admin-only, immediate.
• Role changes: because agents inherit the user’s role, demoting or removing the user cuts their agents down with them.

The read-only alternative: public brand surfaces

If someone just wants an AI to know about your brand, not operate your workspace, they don’t need MCP at all. Every published brand host serves public, no-auth surfaces: /llms.txt as the entry map, machine-readable agent cards, and a POST /ask concierge that answers questions about the brand. Point a reader-style agent there and keep MCP access for the agents that do real work.

For machine-level detail (the full tool inventory, resources, prompts, and the OAuth exchange step by step) see the agent-facing doc at agents/install.