Minds MCP Operating Guide for AI Agents

Tool availability depends on deployment configuration: ordinary discovery exposes 23 tools, or 24 when list_model_connections is enabled, with 42 or 43 canonical tools registered respectively. 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

• 23–24 advertised tools are returned by ordinary tools/list discovery.
• 42–43 canonical tools are registered across Minds, Audiences, Studies, Formations, knowledge, chat, analytics, and exports.
• Additional aliases 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 23–24 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:

plan_study_questions
  -> show the captured objective, main source, questions, methods, and outputs
  -> ask every returned confirmation question
  -> call plan_study_questions again with answers/refinements
  -> obtain explicit confirmation of the exact draft ID and revision
  -> run_study_questions with confirmed: true
  -> poll get_study_run
  -> read or refresh get_study_summary

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.

Confirmation policy

Require explicit confirmation immediately before:

• deleting a Mind, Audience, Study, Formation, chat, knowledge item, or Study draft;
• 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.

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 review text; request revisions in conversation and confirm the latest version before execution. It has no execution button.

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. Retry the exact same payload after a timeout to recover the original 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.