> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.siftsy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.siftsy.com/_mcp/server.

# MCP (beta)

> Beta. Use your Analyst API key from Cursor, Claude, or ChatGPT to read how audiences reacted to a campaign, a viral moment, or a competitor, add new posts, and pull the numbers and quotes for your report.

> **Note**
>
> **Beta.** The MCP is part of the Siftsy Analyst API, and it is in beta. It uses the same key, scopes, and rate limits as the REST API, including the write scopes for adding posts and accounts. Tool names and response shapes can still change. The REST API at `/analyst/v1` is the stable contract for warehouses and scheduled syncs. Use the MCP from a chat, not as a loader.

The Siftsy MCP is the Analyst API for an AI chat. Ask how a campaign landed, what people are saying during a viral moment, or how your posts compare with a competitor's, and the chat answers from your team's Siftsy workspace with scores, themes, and the quotes behind them. Paste a post link and it checks whether Siftsy already has it, and adds it if you say so.

Every post row carries stable join keys, so the chat can line Siftsy's results up with what you already have open in the conversation, such as a campaign tracker or a creator list.

```
https://api.siftsy.app/mcp
```

Send the key as `Authorization: Bearer sk_live_…` (or `sk_test_…`). Monitoring keys (`mk_`) are rejected. The server speaks [streamable HTTP](https://modelcontextprotocol.io) in stateless mode and answers with a single JSON body. There is no session and no server-sent events.

## Connect

#### Cursor

Add this under **Settings → MCP**, or in `~/.cursor/mcp.json`. Use a key from **Team Settings → API**. Turn on `posts:write` / `accounts:write` for that key if the chat should be able to add posts (see [Writes](#writes)).

```json
{
  "mcpServers": {
    "siftsy": {
      "url": "https://api.siftsy.app/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}
```

#### Claude

Claude Code:

```bash
claude mcp add siftsy --transport http https://api.siftsy.app/mcp --header "Authorization: Bearer sk_live_YOUR_KEY"
```

Claude Desktop and claude.ai custom connectors take a URL and OAuth, not a pasted API key. v1 does not speak OAuth. Use the stdio bridge tab for those apps.

#### stdio bridge

Clients that only speak stdio, including some Claude and ChatGPT setups, can bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "siftsy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.siftsy.app/mcp", "--header", "Authorization: Bearer sk_live_YOUR_KEY"]
    }
  }
}
```

> **Note**
>
> The key is a credential. Prefer a `sk_test_` key while you try the connection, and do not commit the header into a repository.

## First session

You do not call the tools yourself. Connect the server, then ask in plain language. A useful first message:

```text
What team is this key on, and which collections do we have?
Scan the last 7 days of [collection name]. Tell me what stands out, then analyze the posts the flags point at.
Cite the analysis id and the Siftsy link.
```

## Use cases

These are the jobs teams use Siftsy for, written as prompts you can paste. Swap in your own collection, brand, and dates.

**Measure how a campaign actually landed.**

```text
Read our [campaign collection] for the last 30 days.
Which creators and posts landed best and worst with commenters, and why?
Give me a per-creator table and three quotes I can put on a slide.
```

**Read the room during a crisis or viral moment.**

```text
Here are the posts carrying the conversation about [topic]:
[paste links]
Check which ones Siftsy has and add the missing ones.
Once they are ready: how is sentiment moving day by day, are commenters arguing with each other,
and what are the main things people are saying? Cite the comments.
```

**See what people say on a competitor's posts.**

```text
Compare @[our brand] and @[competitor] posts from the last 30 days.
Where is the audience reaction different, and what are commenters on their posts responding to?
```

**Turn thousands of comments into themes, and pull the quotes that prove them.**

```text
What are the top themes in the comments on [collection]?
Give each theme's share of comments and the notable comments behind it.
```

**Surface recurring questions, complaints, and requests.**

```text
In [collection], what are commenters asking for or complaining about?
Group them, say how often each comes up, and which posts they cluster on.
```

**Validate a hunch before you spend budget on it.**

```text
Test this against the comments on [collection]: "[the audience thinks the price is too high]".
Does the evidence support it, and on what share of comments and posts?
```

**Explain the why behind engagement numbers.**

```text
Which posts in [collection] had high engagement but negative sentiment?
What were commenters reacting to on those posts?
```

**Line Siftsy up with a campaign tracker you already have.**

```text
Here are the creator post links from our campaign tracker:
[paste links]
Match them to Siftsy, scan the matches, and give me a table I can join back on link.
Say which links are missing and why, and offer to add them.
```

## What to expect

1. The model calls `whoami` and `list_collections` so it knows the workspace.
2. `scan_posts` flags where to look. Flags are not the finding.
3. `analyze` explains why. If it is still running, the model waits and calls `get_analysis`. Do not tell it to poll in a tight loop.
4. `sample_comments` pulls at most 25 notable comments as evidence, not the thread.
5. `export_table` returns rows you can join on `link`. Larger tables come back as a file the client can read.

If the model starts an AI search for "negative comments," stop it. That is a filter. An AI search and a written answer share a small daily budget.

## How to read the results

The tools follow the same path an analyst uses in the product: orient, add, comb, drill, evidence, export.

| Stage    | Tools                                                                                        |
| -------- | -------------------------------------------------------------------------------------------- |
| Orient   | `whoami`, `list_collections`                                                                 |
| Add      | `check_links`, `add_posts`, `add_account`, `refresh_posts`, `get_content_job` (write scopes) |
| Comb     | `find_posts`, `scan_posts`, `breakdown`                                                      |
| Join     | `match_posts`                                                                                |
| Drill    | `analyze`, `get_analysis`                                                                    |
| Evidence | `sample_comments`                                                                            |
| Export   | `export_table`                                                                               |
| Saved    | `list_saved`, `get_saved`                                                                    |

A few rules are built into the tool descriptions, because they are easy to get wrong:

* **content** is what was posted. The scores and mix bars are how commenters responded.
* **Consensus is how commenters react to each other, not to the post.** A thread can be negative toward the post and still high in consensus.
* Read **share of comments** next to **share of content**. 13% of comments across 92% of posts is a broad current. The same 13% on 2 of 12 posts is a flashpoint.
* Scores are 1–10. Shares are 0–1. Mix bars and `engagementRate` are 0–100. Week and month keys are that period's first day.
* A filter stays fast. An AI search, and a written `answer`, share a budget of **2 per minute and 10 per day**. "Negative comments" is a filter, not a search.
* Scan flags say where to look. `analyze` says why.

Every post row includes `postId`, `link`, `platform`, `account` (lowercase, no `@`), `postedAt`, `collectionIds`, and `tags`.

## Analyze

`analyze` creates a 7-day analysis. It does not edit the workspace. Ask for the smallest `parts` that answer the question. `"full"` is stats, scores, content, and a sample of notable comments. It does not write an answer.

| You want                                                     | Ask for                                                        |
| ------------------------------------------------------------ | -------------------------------------------------------------- |
| How did the holiday campaign land?                           | `scores` with dimension `sentiment`, plus `stats`              |
| Are commenters fighting each other during this viral moment? | `scores` with dimension `consensus`, plus `stats`              |
| What is driving the negative comments?                       | a negative filter, `answer` with that question, and `comments` |
| How did sentiment move through the crisis, week to week?     | `timeline` (week by default)                                   |
| The whole picture of a campaign                              | `"full"`                                                       |

`answer` is not available on a comparison. The tool starts one analysis per side and tells you so. Four sides are four answers, which can hit the 2-per-minute cap, so it starts them as jobs. Check each with `get_analysis`. Do not retry a rate limit immediately.

A snapshot usually finishes in the same call. Anything still running comes back as a handle:

```json
{
  "analysisId": "an_…",
  "status": "running",
  "progress": { "phase": "writing", "percent": 10 },
  "ready": [],
  "pending": ["answer"],
  "retryAfterSeconds": 10,
  "next": "Call get_analysis with this analysisId in ~10s."
}
```

`get_analysis` waits up to about 20 seconds for the analysis to finish, so the model makes a few calls rather than a tight loop. The whole HTTP request shares that budget: a batch does not get 20 seconds per call. Analyses last 7 days. A later turn can reuse the `analysisId`. When you write the finding up, cite that id and `links.appUrl` so a teammate can open the same workspace.

## Export and joining

When you paste a post or profile link from TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Reddit, or Pinterest, the model calls `check_links` first. It reports whether each post is already on the team and whether each profile is a saved account. Nothing is added or charged. If something is missing, the model offers to add it to the team and waits for you to say yes. It can only add it when the key has the write scopes (see [Writes](#writes)). Otherwise it tells you what is missing.

`match_posts` takes links from your own campaign tracker or creator list and returns `matchedPostIds` plus a status for every link that did not match. Pass the ids to `scan_posts`, `breakdown`, or `analyze`. Nothing is added or charged.

`export_table` returns up to about 200 rows inline, with the column names (`columns` for an analysis, `csvColumns` for a scan or breakdown). Larger tables come back as a preview plus a `siftsy://` resource. Reading that resource recomputes the CSV and spends another call in the same rate class. Nothing is written to S3.

`sample_comments` returns at most 25 notable comments. It is evidence behind an analysis, not a thread export.

## Prompts

The server ships four prompts: `weekly-readout`, `what-changed`, `join-my-data`, and `evidence-check`. They tell the model which tools to call. They do not run the tools by themselves.

## Writes

Writes are part of the beta. From the chat you can add a new campaign's creator posts, the posts behind a viral moment, or a competitor's recent posts, then analyze them in the same conversation.

| Tool              | What it does                                                                | Scope            |
| ----------------- | --------------------------------------------------------------------------- | ---------------- |
| `add_posts`       | Add posts by URL                                                            | `posts:write`    |
| `add_account`     | Pull a public account's recent posts                                        | `accounts:write` |
| `refresh_posts`   | Pull new comments on posts already on the team (once per post per 12 hours) | `posts:write`    |
| `get_content_job` | Check progress on any of the above                                          | `posts:read`     |

These tools only appear for a key that has `posts:write` or `accounts:write`. Both scopes are off by default. A team admin turns them on per key under **Team Settings → API**.

Adding posts, adding an account, and refreshing spend the team's credits, the same way Add New does in the product. Rejected links are not billed. The model asks before it adds anything. `add_account` always previews first (`dryRun: true`) and shows what it found and what it would cost; it only adds the posts after you confirm. New posts have to process before they can be analyzed. The model polls with `get_content_job` and can analyze them once they are complete. See [Adding content](/guides/core-concepts/adding-content).

## Limits

Each tool reserves the rate class of the REST route it stands for, and the response counts against the daily byte budget. See [Rate limits](/guides/core-concepts/rate-limits). `POST /mcp` itself is not a way around the `analysis_search` cap.