API Reference

The Flashpoint.AI MCP server exposes four 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://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, Cursor, etc.) handle the protocol for you.

When to use which tool

Goal	Tool	Brain
Multi-step plan: design → recruit → field → analyze → deck	`chat`	Full orchestrator — picks tools, runs them, narrates
Population stats for a place	`get_demographics`	Direct dispatch — single worker call
Run a synthetic panel through a known survey	`synthetic_panel_take_survey`	Direct dispatch
Native `.pptx` with editable charts	`create_presentation`	Direct dispatch
Design or modify a survey	`surveys_agent`	Wraps the surveys agent — multi-turn LLM with approval gates

Direct-dispatch tools are faster (one worker, no LLM planning loop). chat is what you want for anything that crosses tool boundaries or needs the orchestrator's memory across a turn.

`chat`

Send a message to Flashpoint.AI and wait for the assistant's reply. The orchestrator decides what to do — call demographics, generate synthetic personas, run a survey, build a presentation — and returns when the turn is complete.

Use when you want the orchestrator's brain (planning + cross-tool memory) rather than driving the flow yourself.

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 (default timeout 300s).

`get_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.

Pricing (wallet agents)

Per call — see the 402 payment terms when calling without payment. Human bearers (Auth0 / OAuth) are not gated.

`synthetic_panel_take_survey`

Run a synthetic panel of AI personas through a real survey. Each persona answers based on its demographic + psychographic profile.

Both panel_id and survey_id are required for this direct path. The chat tool can auto-resolve them from conversation history; this tool cannot.

Parameters

Name	Type	Required	Description
`panel_id`	string	yes	UUID of an existing synthetic panel
`survey_id`	string	yes	UUID of the survey to run

Returns

A worker ToolResult dict — status, result (response counts, completion stats), error, timing.

Timeout

Up to 1800s (30 minutes). Calibrated runs do one LoRA call per question per persona; a 20-persona × 30-question warm run measures ~25 min wall clock. The direct MCP path and the chat-routed path get the same headroom.

`create_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.

`surveys_agent`

Create or modify a survey via the surveys agent — the single entry point into the surveys service. The brief is natural language and the agent runs its own multi-turn LLM loop (planning + its internal toolset) to do whatever the brief asks: author questions, edit existing ones, add branching/skip logic, set quotas, etc. The call may take 60–300s.

Parameters

Name	Type	Required	Description
`brief`	string	yes	What you want done, in natural language — topic, audience, number of questions, quotas, branching, or an edit instruction for an existing survey
`survey_id`	string	no	Pass to continue work on an existing survey; omit to create a new one
`conversation_id`	string	no	Pass the value returned by a previous call to keep refining the same survey in one thread. Omit and the server mints one

Returns

The agent's result blob (typically includes the created/updated survey_id), with the conversation_id echoed back so follow-up calls can thread:

{
  "conversation_id": "<uuid>",
  "survey_id": "<uuid>",
  "...": "..."
}

See Surveys for the broader survey model.

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.