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

{% hint style="warning" %}
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.
{% endhint %}

## Connect your client

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

### Claude Code

```bash
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:

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

### Cursor / VS Code

Add the server to your MCP configuration:

```json
{
  "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`:

```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" }
    }
  }
}
```

## 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 `recommend_*`, `request_*`, and `approve_*` tools, 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 29 tools — 24 read‑only, and 5 (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.               | `expand` (`recommended_publication`, `stats`), `from`, `to`, `page`, `per_page` |
| `list_free_recommendations` | Newsletters you recommend organically, with no commission.                            | `expand` (`recommended_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`, `stats`)                                   |
| `list_earn_offers`          | Brand offers you recommend to earn from.                                              | `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_in_email_campaigns`      | Trackable links you place in your emails.                                                                            | `expand` (`stats`), `from`, `to`, `page`, `per_page` |
| `get_in_email_campaign`        | Get one in‑email 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. | `order_by` (`commission`, `max_payout`), `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) |
| `recommend_free_recommendation` ✎           | Start recommending a newsletter from the directory for free (by its UUID).                     | —                                                                     |
| `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).                             | —                                                                     |
| `approve_partner_request` ✎                 | Approve a pending partner request (by its UUID), turning the applicant into an active partner. | `expand` (`recommending_publication`)                                 |

## 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 five tools are strictly read‑only. The write tools map to the same actions you can already take in the dashboard (recommending an entry, approving a partner).

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