> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/mcp-server.md). # MCP Server SparkLoop exposes a Model Context Protocol (MCP) server, so AI assistants — Claude, ChatGPT, 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. Most people should use OAuth. ### OAuth (recommended) Paste the server URL into your AI client, sign in with your SparkLoop credentials in the browser, and approve the connection — there is no key to copy or store. The chat apps (ChatGPT and the Claude apps) connect this way. The server advertises its OAuth metadata at `/.well-known/oauth-protected-resource` and supports dynamic client registration, so most clients configure themselves. ### API key Developer tools and scripts that let you set request headers can send your SparkLoop API key in an `x-api-key` header instead. You'll find your key in the SparkLoop dashboard under **Settings → Integrations**, in the **Your API Key** section. The **Tools → MCP** page also has a **Copy your API key** link. The key identifies your account, and every tool operates within it. ## Connect your client The chat apps (ChatGPT and the Claude apps) connect with OAuth: you paste the server URL, then sign in to SparkLoop in your browser. The developer tools (Claude Code, Cursor, VS Code) accept OAuth or an API key. {% hint style="info" %} These apps rename their menus often. If a label below doesn't match what you see, look for the option to add a **custom connector** or **custom MCP server**, and paste `https://mcp.sparkloop.app`. {% endhint %} ### ChatGPT Custom MCP servers need ChatGPT's **Developer mode**, which OpenAI currently lists for Plus, Pro, Business, Enterprise, and Edu accounts. You set it up in ChatGPT on the web; Developer mode apps don't work in the ChatGPT mobile apps. 1. Open **Settings → Apps** (formerly **Connectors**), open **Advanced settings**, and turn on **Developer mode**. 2. Back in **Apps**, start a new app. 3. Enter a name (for example, `SparkLoop`) and the URL `https://mcp.sparkloop.app`. 4. For the authentication mechanism, pick **OAuth**. 5. Click **Scan Tools** and wait for the scan to finish. If ChatGPT opens a SparkLoop sign‑in window, sign in and approve the connection. 6. Click **Create**. 7. In a chat, click **+** near the message box, select SparkLoop from the tool list, and ask your question. For tools that change your account, ChatGPT may ask you to confirm first. On a Business, Enterprise, or Edu workspace, only an owner or admin can turn on Developer mode and create the app (under **Workspace settings → Apps**). OpenAI's pages differ on which plans can run tools that make changes (the ✎ tools below), so if those tools don't appear for you, your plan may be limited to the read‑only ones. ### Claude (web and desktop apps) Custom connectors are available on every Claude plan; the Free plan allows one. 1. Open **Customize → Connectors**. 2. Click **+**, then **Add custom connector**. 3. Enter a name (for example, `SparkLoop`) and the URL `https://mcp.sparkloop.app`. You don't need an OAuth client ID or secret, so leave **Advanced settings** as they are. 4. Click **Add**. If Claude doesn't start the sign‑in by itself, click **Connect** on the SparkLoop connector. Sign in to SparkLoop in the browser window and approve the connection. 5. In a chat, click **+**, open **Connectors**, and switch SparkLoop on. Claude asks for your approval before it runs a tool, unless you choose **Always allow** for that tool. If the sign‑in fails, open **Advanced settings** in the connector dialog and choose the option that lets Claude register with the server automatically, then try again. On a Team or Enterprise plan, an owner first adds the connector under **Organization settings → Connectors**. Each member then opens **Customize → Connectors** and clicks **Connect** to sign in with their own SparkLoop account. **Claude mobile apps.** Add the connector on the web or in the desktop app first. It is saved to your Claude account, so it is available the next time you open Claude on iOS or Android. Some Claude accounts also show a **Request headers** option (in beta) in the connector dialog, which can send an API key. OAuth is simpler, so you don't need it. ### Claude Code Add the server, then run `/mcp` inside Claude Code, select `sparkloop`, and follow the sign‑in prompt: ```bash claude mcp add --transport http sparkloop https://mcp.sparkloop.app ``` To use an API key instead of OAuth, pass it as a header: ```bash claude mcp add --transport http sparkloop https://mcp.sparkloop.app \ --header "x-api-key: YOUR_API_KEY" ``` ### Cursor Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). Cursor opens a browser window for you to sign in: ```json { "mcpServers": { "sparkloop": { "url": "https://mcp.sparkloop.app" } } } ``` To use an API key instead of OAuth, add a `headers` entry: ```json { "mcpServers": { "sparkloop": { "url": "https://mcp.sparkloop.app", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Some Cursor versions still start the OAuth sign‑in when a server offers it, even with `headers` set. If that happens, complete the sign‑in. ### VS Code VS Code uses a different file format from Cursor: the top‑level key is `servers`, and each server needs a `type`. Run **MCP: Add Server** from the Command Palette, or add this to `.vscode/mcp.json` (or to your user configuration, via **MCP: Open User Configuration**). VS Code then asks you to sign in: ```json { "servers": { "sparkloop": { "type": "http", "url": "https://mcp.sparkloop.app" } } } ``` To use an API key instead of OAuth, add a header that reads the key from a masked input. VS Code asks for the key once and stores it securely, so the key never sits in the file: ```json { "servers": { "sparkloop": { "type": "http", "url": "https://mcp.sparkloop.app", "headers": { "x-api-key": "${input:sparkloop-api-key}" } } }, "inputs": [ { "type": "promptString", "id": "sparkloop-api-key", "description": "SparkLoop API key", "password": true } ] } ``` ### Other clients (via mcp-remote) Clients that don't yet speak remote MCP natively can bridge through `mcp-remote`. It is also a way to use an API key, rather than OAuth, in Claude Desktop (**Settings → Developer → Edit Config**): ```json { "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" } } } } ``` Keep `x-api-key:${SPARKLOOP_API_KEY}` free of spaces — some clients don't escape spaces in `args`. ## 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. For totals across a whole collection (all paid recommendations, all free recommendations, or all Earn offers), use the matching `get_*_stats` tool instead of expanding `stats` on every row. * **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 42 tools — 28 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`, except on the `get_*_stats` tools, where they always apply. ### 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` | | `get_paid_recommendation_stats` | Paid‑recommendation performance for the whole publication — the totals on the Earn → Paid Recommendations dashboard (referrals, earnings, and signup flow / campaigns channel breakdowns). | `from`, `to`, `stats_grouped_by` (`utm_source`, `utm_campaign`, `country_code`), `stats_group_value` | | `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_free_recommendation_stats` | Free‑recommendation performance for the whole publication — confirmed referrals sent and received, plus current sending / receiving partnership counts. | `from`, `to`, `stats_grouped_by` (`country_code`), `stats_group_value` | | `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` | | `get_earn_offer_stats` | Earn‑offer performance for the whole publication — the totals on the Earn → Offers dashboard (conversions, confirmed earnings, and signup flow / campaigns channel breakdowns). | `from`, `to`, `stats_grouped_by` (`utm_source`, `utm_campaign`, `country_code`), `stats_group_value` | | `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` | | `list_survey_submissions` | Completed submissions for one survey (by `survey_uuid`), newest first — each with the subscriber's email and every answer. Pass `email` to return only that subscriber's submissions. | `email`, `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 OAuth sign‑in or API key, 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.