Skip to navigation

MCP (beta)

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 in stateless mode and answers with a single JSON body. There is no session and no server-sent events.

Connect

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

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

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

StageTools
Orientwhoami, list_collections
Addcheck_links, add_posts, add_account, refresh_posts, get_content_job (write scopes)
Combfind_posts, scan_posts, breakdown
Joinmatch_posts
Drillanalyze, get_analysis
Evidencesample_comments
Exportexport_table
Savedlist_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 wantAsk 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:

{
"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). 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.

ToolWhat it doesScope
add_postsAdd posts by URLposts:write
add_accountPull a public account’s recent postsaccounts:write
refresh_postsPull new comments on posts already on the team (once per post per 12 hours)posts:write
get_content_jobCheck progress on any of the aboveposts: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.

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. POST /mcp itself is not a way around the analysis_search cap.