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 consolidated 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.
• query_products: the product catalog.
• query_surfaces: surfaces and zones (the touchpoints campaigns deploy to).
• query_brand: the brand book, public profile and voice.
• query_analytics: snapshots, A/B tests, the CVG dashboard, insights.
• query_video: video templates and render progress.
• query_video_commissions: the status of commissioned films.
• 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.

Tools that spend credits:

• generate_campaign, render_video, video_commission.

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

Three tools consume your workspace’s monthly creative credits: generate_campaign (AI campaign generation, including AI-generated images), render_video, and video_commission (AI-generated film). 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. When credits run out, the generating action returns a quota error; published campaigns keep serving. 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.