MCP Server

SparkLoop exposes a Model Context Protocol (MCP) server, so AI assistants — Claude, Cursor, and any other MCP‑compatible client — can read and act on your SparkLoop account in plain language. Ask "which of my paid recommendations earned the most last month?" or "recommend the three best programs in the directory for my audience," and the assistant answers using live account data instead of guesswork.

Endpoint

https://mcp.sparkloop.app

The server speaks the Streamable HTTP transport. Point any MCP‑compatible client at this URL — there is nothing to install or self‑host. Opening the URL in a browser won't work; it only responds to MCP clients.

Authentication

Authenticate in either of two ways.

API key

Send your SparkLoop API key in an x-api-key header. You'll find your key in the SparkLoop dashboard under Settings → API. The key identifies your account, and every tool operates within it. This is the quickest way to get connected.

OAuth

Clients that support remote‑MCP OAuth (such as Claude) can sign in with your SparkLoop credentials instead of copying a key. The server advertises its OAuth metadata at /.well-known/oauth-protected-resource and supports dynamic client registration, so most clients configure themselves — you just approve the sign‑in in your browser.

MCP access is enabled per account. If a client connects but every request returns "MCP is not enabled for your account," reach out to SparkLoop support to have it turned on.

Connect your client

Exact steps vary by client and version; the examples below cover the most common setups.

Claude Code

claude mcp add --transport http sparkloop https://mcp.sparkloop.app \
  --header "x-api-key: YOUR_API_KEY"

To use OAuth instead, omit the header — Claude will prompt you to sign in:

claude mcp add --transport http sparkloop https://mcp.sparkloop.app

Cursor / VS Code

Add the server to your MCP configuration:

{
  "mcpServers": {
    "sparkloop": {
      "url": "https://mcp.sparkloop.app",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Omit headers to authenticate with OAuth instead.

Other clients (via mcp-remote)

Clients that don't yet speak remote MCP natively can bridge through mcp-remote:

{
  "mcpServers": {
    "sparkloop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.sparkloop.app", "--header", "x-api-key:${SPARKLOOP_API_KEY}"],
      "env": { "SPARKLOOP_API_KEY": "YOUR_API_KEY" }
    }
  }
}

How the tools work

• Start with a publication. Almost every tool is scoped to one publication, identified by a publication_uuid. Call list_publications first to get one, then pass it to the tools that need it.

• Expand related data. Many read tools accept an expand argument to fold in related objects (for example, the recommended publication behind a recommendation) that are otherwise returned as a UUID.

• Ask for stats. Where a resource has performance data, expand a stats block and set the window with from and to (ISO 8601 dates, YYYY-MM-DD). The default window is the last 30 days.

• Reads vs. writes. Every tool is read‑only except the write tools (marked ✎), which change your account.

• Lists are paginated, identifiers are UUIDs, and monetary amounts are in dollars.

SparkLoop terminology

SparkLoop reuses everyday words with specific meanings. The server hands these definitions to the assistant automatically, but they're worth knowing:

Term	What it means
Publication	A newsletter. Nearly every tool is scoped to one.
Earn vs. Grow	The two sides of an account. Earn is how a publication makes money (recommending other newsletters and brand offers for commission). Grow is how it gains subscribers (running its own partner program and creating offers).
Recommendation	Another newsletter this publication promotes. Paid recommendations earn commission through a partner program; free ones are organic. (Called partner_campaign in v2.)
Partner program	The flip side of a paid recommendation: the program this publication runs to pay other publications (its partners) to recommend it. A partner request is a publication applying to join; a referral is a subscriber a partner sent in.
Offer	A brand/advertiser deal that pays per lead, click, or action — it promotes a product, not a newsletter.
Partner Network	SparkLoop's directory / marketplace. The browse_* tools search it; the recommend_* and request_* tools act on an entry.
Earnings vs. payouts	Earnings is revenue accrued; payouts is money SparkLoop has actually paid you.
Signup flow	The on‑site welcome flow shown to new subscribers (called upscribe in v2).

Available tools

The server exposes 38 tools — 24 read‑only, and 14 (marked ✎) that make changes. Every tool takes the identifiers named in its description (a publication_uuid, and often a resource UUID); the Optional params column lists what else you can pass. from/to set the stats window and only apply alongside expand=stats.

Discovery

Tool	Description	Optional params
list_publications	List the newsletters on your account. Start here — most other tools need a publication_uuid.	page, per_page
get_publication	Get one publication's profile and settings by UUID.	—

Earn — your monetization

Tool	Description	Optional params
list_paid_recommendations	Newsletters you recommend through a partner program to earn commission.	status (active, budget_used_up, paused, awaiting_approval, archived), expand (recommended_publication, stats), from, to, page, per_page
list_free_recommendations	Organic partnerships with no commission — both sending and receiving.	status (active, awaiting_approval, archived), role (sending, receiving), expand (recommended_publication, recommending_publication, stats), from, to, page, per_page
get_recommendation	Get one of your recommendations by UUID (looks up both paid and free).	expand (recommended_publication, recommending_publication, stats)
list_earn_offers	Brand offers you recommend to earn from.	status (active, archived), expand (stats), from, to, page, per_page
list_offer_conversions	The individual leads / clicks / actions recorded against one offer (by offer_uuid).	page, per_page
list_payouts	Partner Network payments SparkLoop has sent you.	page, per_page
get_payout	Get one payout by UUID, with an optional per‑publication breakdown.	expand (details, unpaid_details)

Grow — your audience

Tool	Description	Optional params
get_partner_program	Your own partner program — how you pay others to recommend you.	expand (stats), from, to
list_partners	The publications that recommend you, rank‑ordered.	order_by (newest, confirmed_referrals, earnings), expand (recommending_publication, stats), from, to, page, per_page
list_partner_program_referrals	Subscribers your partners have driven to you.	expand (recommending_partner), page, per_page
list_partner_requests	Pending applications to become a partner.	expand (recommending_publication, partner_track_record), page, per_page
list_grow_offers	Brand offers you created for others to recommend.	expand (stats), from, to, page, per_page

Analytics

Tool	Description	Optional params
get_earnings	Accrued earnings across recommendations and offers, sliceable by campaign, channel, and time.	group_by (utm_campaign, recommendation, offer), channel, granularity (total, daily, weekly, monthly), from, to

Tools — signup flow, campaigns, surveys

Tool	Description	Optional params
get_signup_flow	Your on‑site welcome flow and its performance.	expand (stats), from, to
list_campaigns	Trackable links you place in your emails (campaigns).	expand (stats), from, to, page, per_page
get_campaign	Get one campaign by UUID.	expand (stats, target), from, to
list_surveys	Welcome surveys shown to new subscribers.	page, per_page
get_survey_insights	Aggregated results for one survey (by survey_uuid) — every question and its answer distribution, in a single call.	—
list_survey_question_answers	Individual answers to one question (by survey_uuid + question_uuid) — the only way to read free‑text responses.	expand (question), page, per_page

Partner Network — browse the directory

Tool	Description	Optional params
browse_paid_recommendations	Browse partner programs you can recommend for commission. Each row includes already_recommended.	order_by (commission, max_payout), exclude_recommended, page, per_page
browse_free_recommendations	Browse newsletters you can recommend for free.	q, categories, language, page, per_page
browse_offers	Browse brand offers you can recommend to earn.	q, categories, conversion_types, commission_type, countries, sort (newest), page, per_page

Writes

Tool	Description	Optional params
recommend_paid_recommendation ✎	Start recommending a partner program from the directory (by its UUID).	reason_for_recommending (required by programs that screen partners)
archive_paid_recommendation ✎	Soft-archive a paid recommendation this publication is sending.	—
reactivate_paid_recommendation ✎	Restore a paid recommendation this publication archived. Fails if the sponsor archived it.	—
recommend_free_recommendation ✎	Start recommending a newsletter from the directory for free (by its UUID).	—
archive_free_recommendation ✎	Soft-archive a free recommendation this publication sends or receives.	—
reactivate_free_recommendation ✎	Restore a free recommendation this publication archived. Fails if the other side archived it.	—
request_free_recommendation_partnership ✎	Ask a newsletter to recommend you back (by its UUID).	—
recommend_offer ✎	Start recommending a brand offer from the directory (by its UUID).	—
archive_offer ✎	Soft-archive an offer this publication has joined.	—
reactivate_offer ✎	Restore a joined offer this publication archived. Fails if the brand archived it.	—
approve_partner_request ✎	Approve a pending partner request (by its UUID), turning the applicant into an active partner.	expand (recommending_publication)
enable_signup_flow_stage ✎	Enable one signup-flow stage so new subscribers see it.	stage (recommendations, offers, survey) — required
disable_signup_flow_stage ✎	Disable one signup-flow stage. At least one of recommendations or offers must remain enabled.	stage (recommendations, offers, survey) — required
create_campaign ✎	Create a tracking campaign link for emails.	campaign_type (required: recommendations_hub, specific_recommendation, offers_hub, specific_offer), name, recommendation_uuid, offer_recommendation_uuid

FAQ

How is this different from the REST API? The MCP server is a conversational front door to the same data as the API v3. The REST API is for code you write; the MCP server lets an AI assistant call those same capabilities on your behalf, choosing the right tool and stitching results together.

Is my data safe? The server only ever accesses the single account behind your API key or OAuth sign‑in, and all but fourteen tools are strictly read‑only. The write tools map to the same actions you can already take in the dashboard (recommending or archiving an entry, reactivating one this publication archived, approving a partner, enabling/disabling a signup-flow stage, or creating a campaign).

Which protocol version does it use? The server negotiates the MCP protocol version with your client automatically, so any current MCP client will connect.