API Reference
The Flashpoint.AI MCP server exposes five direct tools plus a chat tool that hands off to the full orchestrator. Every tool runs through the same identity model — see Authentication — and respects per-team scoping.
Endpoint: https://api.flashpoint.ai/mcp (production) · https://mcp-staging.flashpoint.ai/mcp (staging)
Transport: MCP Streamable HTTP over POST. Each request is a JSON-RPC envelope:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "<tool-name>", "arguments": { … } }
}
You don't normally hand-craft these — MCP clients (Claude Desktop, Claude Code, ChatGPT, Cursor, etc.) handle the protocol for you.
When to use which tool
| Goal | Tool | Brain |
|---|---|---|
| Anything about a survey: plan, design, quotas, translate, QA, publish, recruit paid respondents, distribute, analyze, export | tool_survey | Wraps the surveys agent — multi-turn LLM with ~150 internal tools and confirm gates. Every one of them is listed in the MCP capability reference |
| Synthetic respondents: build a persona panel, run it through a survey, or recruit paid respondents | panel | Direct dispatch (recruit delegates to the surveys agent) |
| Population stats for a place | demographics | Direct dispatch — single worker call |
Native .pptx with editable charts | presentation | Direct dispatch |
| Settle an x402 panel payment (wallet agents only) | payment_confirmation | Direct |
| Multi-domain plan in one shot, or orchestrator-only capabilities (ad experiments, research scoping, team files, maps, asking a panel a question) | chat | Full orchestrator — picks tools, runs them, narrates |
Direct-dispatch tools are faster (one worker, no second LLM planning loop). Send all survey work to tool_survey, not chat — the surveys agent already plans and runs multi-step survey flows itself, and routing it through chat adds a redundant LLM hop and a longer handshake.
The older tool names surveys_agent, create_panel, and get_demographics are still registered as deprecated aliases of tool_survey, panel(action="create"), and demographics.
tool_survey
The single entry point for anything survey-related. Hand it a natural-language brief; the surveys agent runs its own multi-turn loop (planning plus a large internal toolset) and takes the next steps itself. You do not chain individual operations.
What it covers
| Area | Capabilities |
|---|---|
| Plan & research | Clarify the objective, research the market / audience / competitors, propose a blueprint before building; start from a template or save a survey as one |
| Design | 20+ question types (single, multi, grids, ranking, MaxDiff, conjoint / CBC, image compare, spatial allocation, thermometer, sliders, open ends, contact form, AI-moderated interview); blocks with rotation / randomization, answer lists, skip and display logic, piping, loops, URL variables, redirect URLs, derived values, exclusive options, data validation |
| Quotas & sample sources | Quota cells, least-fill, quota sheets, progress / reconcile / export; bring-your-own sample sources with per-vendor links and redirects; first-party and custom panels |
| Languages | Add survey languages, machine-translate, review or set individual translations |
| Validation & QA | surveycheck logic prover, publish readiness, DSL validation, QA rounds with findings, walk a respondent path, field report, client review link |
| Launch & lifecycle | Publish, pause, resume, complete, clone, transfer; version history, compare, restore, undo |
| Paid recruitment | Prolific, Dynata, Cint: browse filters and markets, get a quote, then on confirmation a secure checkout link; panel status / pause / resume after launch |
| Distribution | Email lists and templates, invitations, reminders, send to a panel, send reports |
| Data quality | Speeders, straightliners, quality summary, exclude responses, generate test data |
| Analysis & exports | Frequencies, crosstabs with stat tests, NPS, open-end themes, AI summaries and key takeaways; conjoint analytics (market simulator, willingness-to-pay, sensitivity, segments, product optimizer, share link); CSV / XLSX / DOCX / PDF exports; results dashboard |
| Collaboration | Comments on questions, resolve threads |
Interactive cards (plan, approval, results dashboard, conjoint simulator, checkout) render in the Flashpoint.AI web app, not in your assistant. The text reply carries the substance, and every MCP conversation is also visible at app.flashpoint.ai afterwards.
Confirm pattern
Money and destructive actions (publish, delete, send emails, paid recruitment) are never performed on the first ask. The agent replies asking you to confirm; your assistant relays that, and you call again on the same conversation_id with the confirmation (e.g. "confirm"). Nothing is charged without that explicit second step. For paid recruitment the confirmation returns a hosted Stripe Checkout link you open in a browser.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
brief | string | yes | What you want done, in natural language — a build spec, an edit, a recruitment request, an analysis ask, an export, a confirmation |
survey_id | string | no | Pass to act on an existing survey; omit to create a new one |
conversation_id | string | no | Pass the value returned by a previous call to continue the same thread. Required to keep context across build → recruit → analyze and to satisfy a confirm step. Omit on the first call and the server mints one |
Returns
The agent's result blob (typically includes the relevant survey_id), with the conversation_id echoed back so follow-up calls can thread:
{
"conversation_id": "<uuid>",
"survey_id": "<uuid>",
"...": "..."
}
The call may take 60–600s. Clients that send a progressToken receive progress notifications for each agent step while it runs.
See Surveys for the broader survey model.
panel
Manage respondent samples — synthetic personas and paid recruits. Routing is by action:
action | What it does | Required |
|---|---|---|
create | Build a synthetic panel of AI-generated personas (max 200). Returns a panel_id | name, num_respondents, research_objective |
create_and_run | Build a fresh synthetic panel and run it through a survey in one call. Progress streams via MCP progress notifications; long runs (~45 min) survive idle timeouts | name, num_respondents, research_objective, survey_id |
run | Not supported on the direct path — an existing panel's personas live in the orchestrator's artifact store. Use create_and_run, or ask chat to run the panel by id | — |
recruit | Real paid respondents from Prolific / Dynata / Cint. Delegates to the surveys agent's quote → confirm → checkout flow | survey_id (for a quote) or request (free-text catalog browse) |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | string | yes | create, create_and_run, run, or recruit |
name | string | create | Panel name |
num_respondents | integer | create | Persona count, 1–200 |
research_objective | string | create | What the panel is for — shapes the personas |
context | string | no | Extra grounding, e.g. real distributions from demographics |
audience | object | no | Structured audience targeting |
survey_id | string | create_and_run, recruit | Survey to run or to quote recruitment for |
provider | string | no | prolific, dynata, or cint |
request | string | no | Free-text catalog question for recruit, e.g. "what Prolific filters are available?" |
conversation_id | string | no | Thread follow-up recruit calls (quote → confirm) |
Returns
A worker ToolResult dict — status, result, error, and timing. create_and_run returns both the panel_id and the run result.
demographics
Population, age, race, gender, education, and income distributions with AI-powered insights. US locations are sourced from the US Census Bureau; international locations come from a curated city/country database.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
location | string | yes | A US zip code, city name, country, or any human-readable place |
question | string | no | Sharpen the response — e.g. "focus on adults 25–44 with a college degree" |
audience | string | no | Override the implied audience — e.g. "small-business owners" |
Returns
A worker ToolResult dict — status, result, error, and timing.
presentation
Generate a native PowerPoint (.pptx) deck with editable charts.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
title | string | yes | Deck title |
data_context | string | yes | Survey, analysis, or any text-form data the deck should be built from |
custom_instructions | string | no | Tone, brand notes, structure overrides |
max_slides | integer | no — default 12 | Clamped to 2–30 |
Returns
A worker ToolResult dict. When S3 is configured the deck is uploaded and a download_url is returned; otherwise the raw .pptx is base64-encoded as pptx_base64.
payment_confirmation
Settle an x402 panel payment intent and trigger the panel launch. Autonomous wallet agents only — humans complete panel payment through the Stripe Checkout link the surveys agent returns, not through this tool.
Call it after tool_survey (or chat) returns an x402_payment_required envelope, passing the envelope's intent_id. The x402 middleware paywalls this tool by the intent's exact amount: the first call returns a 402 with the on-chain payment requirements (EIP-3009 on Base USDC); sign the authorization, retry with the X-PAYMENT header, and the facilitator settles the transfer. The panel starts launching once the settle succeeds.
| Name | Type | Required | Description |
|---|---|---|---|
intent_id | string | yes | The intent_id from the x402_payment_required envelope |
chat
Send a message to Flashpoint.AI's server-side orchestrator and wait for the assistant's reply. The orchestrator decides what to do and returns when the turn is complete.
Use when you want a multi-domain flow planned in one shot (e.g. demographics + a synthetic panel + a presentation), or for capabilities that have no direct tool yet:
- Ad and market experiments on Google, Meta, or LinkedIn Ads: build variants, run synthetic personas through them before spending budget, launch, and analyze campaign results
- Research scoping: decide what to research, pick a methodology, draft a Statement of Work
- Existing synthetic panels: ask a panel a single question, list the team's panels, run or calibrate a panel by id
- Team file library: search and read the team's surveys, results, panels, and documents
- Maps of places or regions
Do not route survey work here — use tool_survey.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
message | string | yes | What you want Flashpoint.AI to do, in natural language |
conversation_id | string | no | Pass the value returned by a previous call to continue the same conversation. Omit to start a new thread |
Returns
{
"conversation_id": "<uuid>",
"reply": "<assistant text — the full turn>"
}
The call blocks until the orchestrator finishes the turn (timeout 600s).
Pricing (wallet agents)
Humans signed in through OAuth are not charged per call — usage is covered by the Flashpoint.AI subscription. Autonomous wallet agents pay per call in USDC over x402 on Base; calling without payment returns a 402 with the terms. Defaults: chat $0.01, demographics $0.05, tool_survey $0.50, presentation $0.25, panel $0.50 (create), $0.60 (create_and_run), $0.50 (recruit). A call whose worker returns an error is not settled.
Discovery endpoints
For programmatic clients that need to spin up the OAuth flow:
| Path | What |
|---|---|
GET /.well-known/oauth-protected-resource | RFC 9728 protected-resource metadata |
GET /.well-known/oauth-authorization-server | RFC 8414 authorization-server metadata |
POST /oauth/register | RFC 7591 dynamic client registration |
GET /oauth/authorize | Standard OAuth 2.1 + PKCE entry point |
POST /oauth/token | Authorization-code exchange |
You shouldn't need to call any of these by hand if you're using a standard MCP client.
Surveys REST API
Most surveys operations are also available as a REST API directly against the surveys service. See Surveys › Build and the per-area pages (Lifecycle, Distribute, Analyze, Import & export) for endpoint paths and payloads.