Populous MCP developer guide

The Populous MCP server lets AI clients plan, launch, monitor, and analyze Populous simulations through a structured tool interface.

Use the MCP server when an AI client needs to turn a user request, audience, and supporting context into a Populous simulation without manually building every resource in the web app. The tools are designed around the normal simulation lifecycle: define who to simulate, define what they should evaluate, launch the run, then interpret the results.

How Populous simulations work

A Populous simulation has three core resources:

1. Population: the synthetic audience to simulate.
2. Experiment: the task, survey, website test, or stimulus the audience should evaluate.
3. Simulation run: the execution that connects one population to one or more experiments and returns results.

Clients should let Populous plan and create these resources from a structured brief. Saved population and experiment keys can be inspected for reference, but they are not part of the chat launch flow.

Quickstart

Supported launch workflow

Use this flow for open-ended user requests, including questions, audiences, websites, documents, images, scenarios, business decisions, product ideas, and exploratory prompts.

If the user wants to include local files as context or stimulus, create an upload session first with getAssetUploadLink, wait for the upload, then call listSessionAssets. You can pass individual asset_id or gcs_path values into the brief, or pass upload_session_id into planSimulation or runFromBrief and let the server attach every confirmed asset automatically.

getWorkflowGuide
planSimulation
runFromBrief
getSimulationStatus
getSimulationAnalysis

Workflow:

1. Call getWorkflowGuide once so the client has the current tool sequence in context.
2. Call planSimulation to turn the user's request into a simulation_brief, review_summary, and recommended_component.
3. Let the user review or edit the brief when the client experience supports review.
4. Call runFromBrief with the reviewed brief and recommended component.
5. Poll getSimulationStatus until the run is complete.
6. Call getSimulationAnalysis to return the main answer and supporting evidence.

This is the only supported launch path for chat clients. It keeps population creation, experiment creation, stimulus handling, and launch mechanics inside Populous.

Read-only discovery

Use discovery tools only when the user explicitly asks to inspect saved resources or prior runs.

getWorkflowGuide
listPopulations
listExperiments
listSimulations
getSimulationSetup
getPopulationStats

These tools are informational. Do not use returned population_key or experiment_key values to launch a new chat run. To clone or branch an existing simulation, fetch setup, edit the simulation_brief, and launch with runFromBrief.

MCP server capabilities

Tool reference

Workflow guidance

getWorkflowGuide

Call this once at the start of a new MCP session. It returns the supported launch workflow, supporting tools, and common pitfalls.

The other tool descriptions point clients back to getWorkflowGuide by design. Keeping this guidance in context reduces tool-ordering mistakes, especially around the old keyed workflow that is no longer part of the chat surface.

Use it when:

• A new MCP session starts.
• A client needs to confirm the current launch workflow.
• You are debugging a bad tool sequence.

Population tools

listPopulations

Lists the authenticated user's saved population filters. The response is keyed by population_key.

Use it when:

• The user explicitly asks which populations they have.
• You are checking what populations the account already has.
• You need metadata for a saved audience before calling getPopulationStats.

Do not use it as part of the launch flow. planSimulation returns a brief, and runFromBrief creates a fresh population from that brief automatically. Do not call listPopulations between planning and launch to wait for a newly described population to appear.

getPopulationStats

Returns attribute statistics for a saved population's synthetic individuals.

Use it when:

• The user asks what a population looks like demographically.
• You want to compare two populations.
• You want to break down results by attributes such as age, income, education, or other available fields.

Call it without attributes first to discover available columns. Then call it again with a comma-separated list, such as age,income,education.

Experiment tools

listExperiments

Lists the authenticated user's saved experiments. The response is keyed by experiment_key.

Use it when:

• The user explicitly asks which experiments they have.
• You are checking what experiments the account already has.

Do not use it as part of the launch flow. runFromBrief creates the experiment from recommended_component automatically.

Planning and launch

planSimulation

Use planSimulation as the entry point for most user requests. It converts the user's request into:

• simulation_brief: the structured simulation plan.
• review_summary: a short reviewable summary.
• recommended_component: the first experiment Populous recommends running.

Call it with a specific prompt and any useful context. The normal output includes population_items in describe mode; pass that brief through to runFromBrief instead of looking up or injecting saved population keys.

Use it when the user starts from:

• A question.
• A business decision.
• A product, ad, page, website, mockup, or document.
• A target audience.
• An exploratory "what would happen if..." scenario.
• Planning context or stimulus that needs to become a rigorous simulation.

Keep planning context separate from respondent-visible stimulus:

• Planning context informs the experiment design.
• Simulation stimulus is what respondents should actually see or interact with.

For example, a strategy memo may belong in planning context, while an ad image should be attached as simulation stimulus. Respondent-visible URLs strongly steer the planner toward a website test.

For local files, call getAssetUploadLink before planSimulation unless you already have a durable asset_id, gcs_path, or public HTTPS URL. Do not pass base64 or data: URLs through tool arguments.

If you have a completed upload session, pass upload_session_id into planSimulation and the server will attach every confirmed uploaded asset to the brief. uploaded_assets_audience controls whether those assets are treated as planning context or simulation stimulus; the default is simulation.

runFromBrief

Launches a simulation from a reviewed simulation_brief, usually with the recommended_component returned by planSimulation.

runFromBrief handles the launch mechanics that the web UI usually manages. It can:

• Create a fresh population from the audience description in the brief.
• Create the experiment from recommended_component.
• Derive the experiment from the brief when no component is provided.
• Promote simulation-visible context into live run stimuli.
• Start the simulation.
• Return the created population, experiment, and simulation metadata.

Use it when:

• You used planSimulation.
• The user reviewed or accepted the brief.
• You want Populous to handle population and experiment creation.

Respondent-visible files should already be referenced in the brief as asset_id, gcs_path, or a public HTTPS URL. If the user still needs to upload files, call getAssetUploadLink first instead of passing inline file bytes.

You can also pass upload_session_id into runFromBrief; the server will attach every confirmed uploaded asset from that session before deriving runtime stimuli.

Do not pass population_key, experiment_key, or population_filter. Those are not launch arguments for the chat surface. If runFromBrief returns successfully, keep the returned sim_key and poll getSimulationStatus; do not wait for a population build to appear first.

Assets and stimuli

getAssetUploadLink

Creates a short-lived upload session for local files the user wants to include as planning context or simulation stimulus.

Use it when:

• The user has local images, ads, screenshots, mockups, PDFs, documents, or other files.
• You generated an image, chart, or document in chat and it needs to become simulation stimulus.
• You do not already have an asset_id, gcs_path, or public HTTPS URL.
• A chat client cannot send file bytes through MCP tool arguments.

It returns a session_id and an upload_url. The user opens the URL to upload files. After upload, call listSessionAssets with the session_id.

Supported upload types include images, PDFs, DOCX, RTF, HTML, plain text, Markdown, CSV, TSV, JSON, and XML. Files are limited to 20 MB each and 25 files per session.

listSessionAssets

Lists the files uploaded in a getAssetUploadLink session. It returns asset records such as asset_id, gcs_path, filename, MIME type, size, and signed URL.

Use it when:

• The user has finished uploading files.
• You need durable file references to put in planning_context_items, simulation_stimulus_items, or context_items.
• You want to avoid asking the user to copy asset IDs back into chat.

After this call, you can either copy individual asset_id or gcs_path values into the brief, or pass upload_session_id into planSimulation or runFromBrief and let the server attach all confirmed files automatically.

uploadSimAssets

Wraps already-resolved file references or plain text into simulation-ready stimuli.

Use it for:

• Files already uploaded to Populous, referenced by asset_id or gcs_path.
• Publicly hosted HTTPS URLs.
• Extracted text, Markdown, HTML, or document text.
• Mixed batches of resolved assets and text snippets.

Do not use uploadSimAssets for raw local files or chat attachments. Call getAssetUploadLink first, then pass the returned asset_id or gcs_path here. The server rejects base64 and data: URL uploads at the MCP boundary.

For planning-only context, prefer putting the asset references directly into simulation_brief.context_items or planning_context_items.

getSimulationStimuli

Returns the canonical stimulus bundle for a simulation, including fresh signed URLs for GCS-backed images and legacy stimulus fields.

Use it when:

• You need to inspect what respondents received.
• You need to debug missing images or documents.
• You want to reuse stimulus assets for a rerun.

Monitoring and results

listSimulations

Lists the authenticated user's simulations with status and keys.

Use it when:

• The user asks what simulations exist.
• You need to find a prior sim_key.
• You are checking whether a run exists before importing or rerunning.

getSimulationStatus

Gets the current status for a simulation.

Use it after runFromBrief.

Typical sequence:

runFromBrief
getSimulationStatus
getSimulationStatus
getSimulationStatus
getSimulationAnalysis

Wait for the simulation to complete before requesting analysis.

getSimulationAnalysis

Returns the main interpreted answer for a completed simulation.

It includes:

• verdict: the concise, citation-grounded answer when evidence converges.
• inconclusive_because: why the result was inconclusive, if applicable.
• keyFindings
• hypothesisValidation
• quoteHighlights
• questionResults
• respondentProfiles
• pathSummary

Use this first when the user asks what the simulation found.

getSimulationResults

Returns the full stored results JSON for a completed simulation.

Use it when:

• You need raw output.
• You are debugging.
• You need details beyond the analysis summary.
• You are building a custom report or downstream transformation.

For user-facing answers, prefer getSimulationAnalysis.

getSimulationSetup

Returns the editable setup for an existing simulation:

• Saved simulation_brief.
• population_key.
• experiment_key or experiment_keys.

Use it when:

• The user wants to clone a run.
• The user wants to branch a run.
• The user wants to revise a prior brief and launch a new run.
• The user wants to inspect the population and experiment keys used by an existing run.

Edit the brief client-side and call runFromBrief. The returned keys are informational; runFromBrief does not accept them as launch arguments.

Sharing and import

importSimulation

Imports a simulation shared by another user into the authenticated account.

Use it when:

• The user has a shared /run?sim_key=... URL.
• The user wants full access to another user's shared simulation.
• The user wants to rerun, inspect, or analyze a shared simulation inside their own account.

Common pitfalls

Skipping planSimulation

If the user starts with an open-ended question, call planSimulation before creating populations or experiments.

Building experiments separately

runFromBrief uses recommended_component to create the experiment automatically. Do not build experiments separately between planSimulation and runFromBrief.

Using the old keyed launch flow

The chat surface no longer exposes a keyed launch path. Do not call old launch tools or try to pass population_key, experiment_key, or population_filter into launch. The brief is the source of truth, and runFromBrief creates the needed resources.

Waiting for population creation

Do not call listPopulations between planSimulation and runFromBrief, and do not wait for the described population to appear before launching. runFromBrief returns a sim_key immediately while population build and simulation queueing proceed.

Mixing planning context with respondent-visible stimulus

Background research, notes, decks, and strategic context can help Populous design the simulation, but they are not always assets respondents should see.

Use planning context for design inputs. Use simulation stimulus for material the synthetic audience should evaluate directly.

Passing inline file bytes

Chat clients cannot send local file bytes through MCP tool arguments. Do not pass base64 fields or data: URLs into planSimulation, runFromBrief, or uploadSimAssets. Use getAssetUploadLink, then listSessionAssets, and pass the returned asset_id or gcs_path, or pass upload_session_id.

Requesting analysis too early

A simulation must complete before getSimulationAnalysis or getSimulationResults can return useful output. Poll getSimulationStatus first.

Examples

New exploratory simulation

User request:

Would mid-market HR leaders trust this onboarding automation product?

Tool flow:

getWorkflowGuide
planSimulation
runFromBrief
getSimulationStatus
getSimulationAnalysis

Use this flow because the user starts from a question and context that Populous should turn into a simulation brief.

Branch a prior simulation with a new audience

User request:

Run the same pricing survey, but this time on finance leaders.

Tool flow:

getWorkflowGuide
getSimulationSetup
runFromBrief
getSimulationStatus
getSimulationAnalysis

Use this flow because the prior run has a saved brief. Fetch the setup, revise the audience in simulation_brief, and launch the revised brief with runFromBrief. Do not launch with saved population or experiment keys.

Clone or branch a prior simulation

User request:

Take the last run and test the same idea with a more technical buyer.

Tool flow:

getWorkflowGuide
getSimulationSetup
runFromBrief
getSimulationStatus
getSimulationAnalysis

Fetch the setup, revise the brief, then use runFromBrief. Returned keys are informational.

Add images or documents as stimuli

For local files:

getAssetUploadLink
User uploads files through upload_url
listSessionAssets
planSimulation or runFromBrief with upload_session_id or asset_id/gcs_path references

For public URLs or extracted text:

uploadSimAssets
runFromBrief with returned stimuli

Public image URLs can be passed directly. Local files should go through the upload session flow so the server receives durable asset_id or gcs_path references.

Operational notes

• The MCP tools read authentication from the connection. Do not ask the user for a token inside tool arguments.
• Keep simulation_brief and recommended_component intact unless the user explicitly edits them.
• Treat keys as opaque strings. Do not parse or construct them.
• When the correct path is unclear, prefer planSimulation followed by runFromBrief.
• Do not use saved population or experiment keys for launch; they are informational in chat workflows.
• For local files, use getAssetUploadLink and listSessionAssets; do not inline base64 or data: URLs.
• Use getSimulationAnalysis for user-facing answers and getSimulationResults for raw data.