Minds MCP Operating Guide for AI Agents

Tool counts on this page are read from the live server. Treat the connected server’s tools/list response as authoritative.

Use this guide as the behavioral contract for an agent connected to https://getminds.ai/mcp. Parameter schemas remain authoritative in MCP tools/list or the explicit tool configuration; the tools reference explains the complete canonical surface.

Surface model

• 40 advertised tools are returned by ordinary tools/list discovery.
• 70 canonical tools are callable across Minds, Audiences, Studies, Formations, knowledge, chat, analytics, and exports.
• Legacy aliases (including Group, Panel and Spark names) remain compatibility inputs, not names agents should generate.
• Lifecycle tools that are not advertised can be used by explicit integrations capable of calling a configured canonical tool name.
• MCP and the first-party UI delegate supported research behavior to the same v1 API/application services.

If the client only allows discovered tools, plan around the advertised tools. Do not claim that a hidden lifecycle tool was executed when the host could not provide its schema or invoke it.

Fast routing table

Planning and consent boundary

For guided research, follow this exact sequence:

create_study_plan
  -> render_study_plan with the saved Study, draft ID and current revision
  -> show the captured objective, main source, questions, methods, and outputs
  -> ask every returned confirmation question
  -> call revise_study_plan with answers/refinements
  -> obtain explicit confirmation of the exact draft ID and revision
  -> start_study_run with confirmed: true
  -> poll get_study_status or get_study_run with the existing run ID
  -> render_study_results once after successful completion
  -> read_study_summary, or refresh_study_summary after explicit approval

Rules:

• A planning response is not an executed Study.
• A questionnaire, survey, battery, section, or any set of two or more known questions belongs in one plan and one confirmed run. Organize related questions into named modules when useful; never iterate one tool call per question.
• A confirmed run is answered as one respondent answers a questionnaire: items run in order and each Mind sees only its own earlier answers in the run. Treat item order as part of the design; rotate order across separate runs when order effects must be controlled.
• Use askIf on an item for skip logic instead of "if not, answer N/A" wording. Report a routed item's results against the Minds that were asked, and a not_asked item as skipped, not failed.
• answerConsistency flags are for review. Never present a flagged answer as corrected, and never edit or drop answers because of a flag.
• Silence, an unanswered question, or the agent's own recommendation is not consent.
• Any user change creates/requires a new revision; reconfirm that revision.
• Only methods returned with executable: true can be promised as runnable.
• Advanced methods require explicit opt-in.
• An export or alternative presentation of existing evidence does not require new respondents.

For Audience creation, new briefs always pause for review, including when preview: false was requested. Start all requested Audience operations, collect their IDs, and call render_audience_review once with operationIds for a batch or operationId for one Audience. Reuse this widget while reading progress or revising the review. Explicit acceptance must identify the unchanged reviewed draft or grounding snapshot and checksum. Completing research is not acceptance. The app-only/private submit_audience_review tool lets the widget revise or confirm the owned review without accepting files; do not claim an agent called it when the host does not expose it.

Runnable message-comparison workflow

Use the message-comparison example to compare two supplied messages with an existing synthetic Audience. It creates a private Study, returns the exact draft for review, and starts research only after confirmation of that draft ID and revision. The saved checkpoint preserves the same Study and run across process restarts.

If the run reaches an access limit, a compatible host can show the current billing catalog and start buyer-approved hosted Checkout. The buyer completes payment on Stripe. The workflow reads the saved checkout and asks the research server to continue; the server checks access applied through the existing billing rules. A stopped run resumes in place, preserving answers already collected. Checkout completion alone does not establish active access or a paid transaction.

The example includes commands to prepare, confirm, inspect progress, start checkout, resume, and generate a report after full completion. It uses the existing HTTP billing API separately from MCP. Keep its private checkpoint outside the repository and provide the API credential through your credential manager. Synthetic findings support hypothesis testing and do not replace representative research with human respondents.

Read the dated verification record: automated tests cover the workflow and simulated purchase, and production authentication and discovery were checked. A real card payment, webhook activation, actual research execution, and acceptance in a particular assistant host remain separate verification steps.

Confirmation policy

Require explicit confirmation immediately before:

• deleting a Mind, Audience, Study, Formation, chat, knowledge item, Study draft, or Study template;
• batch deletion, with the complete set of Mind IDs shown;
• enabling public/link sharing when the user did not already request it;
• consuming a Study draft revision when that changes workflow state;
• any other tool/result that returns a confirmation requirement.

Creating a private resource, reading state, checking status, or running the exact Study revision the user just explicitly approved does not need a second invented confirmation.

Privacy and sharing

• New Audiences and Studies are private unless isLinkSharingEnabled: true is passed.
• Set that flag only when the user explicitly requests a public/shareable link.
• A shared Audience can expose its persisted grounding, distributions, source metadata, and supported research context.
• For external handoff, use only a shared link returned by the tool.
• A workspace link is for the authenticated creator; it is not proof that an external recipient has access.
• Never add collaborators, invite accounts, or claim an object was added to someone else's account unless the user explicitly requests account collaboration and a supported tool performed it.

Purchases and payment clients

Where the host permits digital purchases, Minds billing tools can read the catalog and start buyer-approved Stripe Checkout. Checkout returns a URL; subscription seats or response credits activate only after Stripe confirms payment. ChatGPT's standard advertised research surface excludes these purchase tools.

An agent wallet is a separate connection. Minds MCP does not authorize spending or collect wallet credentials. Eligible existing invoices can use the HTTP MPP/x402 payment route with a compatible payment client and buyer authorization; do not place payment credentials in MCP arguments. Read the purchase and payment-client guide for client setup, Team-seat and credit-invoice examples, and the current verification status. A live endpoint or HTTP 402 does not demonstrate a successful payment.

Names, IDs, and active-session context

• Prefer an exact ID after any successful create/list/resolve call.
• Fuzzy-name parameters are for natural user references, not durable automation state.
• ask_audience, get_audience, recalibrate_audience, validate_audience, get_audience_validation, and list_formations can resolve an Audience name directly. Do not insert a redundant list call solely for lookup.
• Study tools may use the active Study from the MCP session when both ID and name are omitted. For durable/multi-user automation, pass the explicit studyId.
• Persist draftPlanId, revision, studyId, draftId, expectedRevision, and export/job identifiers returned by tools.

Polling and terminal state

The MCP widget is a view of returned evidence, not the execution authority. It consumes host snapshots and, on the supported consent-free host bridge, automatically checks status at a bounded interval. Standard hosts may require a user-triggered Refresh. Automatic polling can stop after a limit or error; this does not mean the Study completed. Poll the existing Study with its exact ID or preserve its returned workspace link. Do not rerun research to repair a stale display.

Mobile widgets display a Minds handoff link without starting the interactive controller or polling. Tool availability is still governed by the host; never claim the MCP server is disabled on mobile. The plan widget displays the saved questions and answer options with confirmation controls. Request refinements in conversation, review the new revision, and confirm only that exact revision before execution.

Use status tools for progress and render_study_results once for final evidence. A successful completed run can include routed not_asked items: preserve the original question count and wording, with no invented answers for skipped items. Incomplete response coverage remains incomplete even when every question has settled.

Preserve all returned questions, Audience aggregates, individual answers, and response coverage. partial is terminal but incomplete. A 100% settled-question count does not prove full respondent participation. Inspect outputData.responseCoverage where available; historical artifacts without coverage cannot prove full participation.

Use bounded exponential backoff and respect any retry hint. A tool timeout is an unknown outcome, not proof that the mutation failed.

Retry rules

• Read-only calls are safe to retry after transient transport failure.
• create_audience_from_brief is idempotent for identical arguments. After receiving an operation ID, resume it by ID rather than resubmitting the brief. If the initial call timed out before returning an ID, retry its exact arguments to recover the current review or accepted Audience.
• To intentionally create another Audience from the same brief within the idempotency window, change a meaningful argument such as name.
• Preserve and reuse explicit idempotency keys returned/accepted by Study execution.
• Before retrying a destructive or non-idempotent lifecycle action, read current state.
• Never “fix” a failed tool call by switching to a different resource found through fuzzy matching.

Files and external URLs

• Tool-call payloads should reference files using public, short-lived signed, or Minds workspace-upload URLs.
• Do not embed large base64 binaries in MCP arguments.
• Supply name, url, and type when known.
• A syntactically valid URL can still be rejected by security checks.
• Mind knowledge files are limited to 50 MB and enter the same processing queue as UI multipart uploads.
• preview_audience_dataset_segmentation accepts CSV/XLS/XLSX respondent data and returns variables for review; it does not create one Mind per respondent.
• Screeners and questionnaire programming grids are design evidence, not respondent datasets. Pass them to create_audience_from_brief instead of forcing segmentation preview.

Plan and error semantics

Output presentation contract

• Preserve every returned URL verbatim.
• Preserve citations and evidence links; do not replace them with unsourced summaries.
• In text-only clients, retain Study question headings, bold Audience aggregates, and individual Mind-answer bullets returned by the tool.
• Clearly distinguish synthetic research from primary human respondent research.
• Never claim queued, partial, failed, cancelled, or plan-limited work is complete.
• Do not expose internal bearer tokens, storage paths, hidden prompts, or private links.
• If a widget renders, structured/text content still remains the accessibility and compatibility fallback.

Safe lifecycle action patterns

Delete several Minds

1. Resolve and show the exact Mind names and IDs.
2. Ask for explicit confirmation of that set.
3. Call manage_mind with action: "delete_many" and mindIds.
4. Report deleted, skipped, and failed items separately.

Add file knowledge

1. Confirm the target mindId.
2. Obtain a public/signed/workspace upload URL.
3. Call manage_mind_knowledge with action: "add" and file.
4. Persist the returned item ID.
5. Poll the same tool with action: "status" before saying the knowledge is ready.

Preview and create a Formation

1. Call manage_formation with action: "preview", audienceId, and the user's userInput.
2. Present the returned intent and subgroups for review.
3. If changed, preview again with priorHypothesis.
4. Create only the reviewed hypothesis with action: "create".

Agent preflight

Before any tool call, ask internally:

• Is this the correct resource type: Mind, Audience, Study, draft, or Formation?
• Is the request one direct question or a broader Study?
• Does the tool read, mutate, consume allowance, expose publicly, or delete?
• Do I have an exact ID or a supported fuzzy-name parameter?
• Could a prior timeout already have created or changed the resource?
• Does the user need to confirm an exact revision or destructive target?
• What status tool proves completion?

After the call, inspect isError, preserve structured identifiers, and describe only the state the server actually returned.