---
title: "Minds MCP Operating Guide for AI Agents | Minds"
canonical_url: "https://getminds.ai/mcp/de/agents"
last_updated: "2026-09-30T14:33:04.086Z"
meta:
  description: "Routing, confirmation, privacy, polling, retry, file, error, and presentation rules for agents using the Minds MCP server."
  "og:description": "Routing, confirmation, privacy, polling, retry, file, error, and presentation rules for agents using the Minds MCP server."
  "og:title": "Minds MCP Operating Guide for AI Agents | Minds"
  "twitter:description": "Routing, confirmation, privacy, polling, retry, file, error, and presentation rules for agents using the Minds MCP server."
  "twitter:title": "Minds MCP Operating Guide for AI Agents | Minds"
---

Minds

Minds Team # **Minds MCP Operating Guide for AI Agents** Routing, confirmation, privacy, polling, retry, file, error, and presentation rules for agents using the Minds MCP server. 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](https://getminds.ai/mcp/tools) 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 | User intent | Tool | Important behavior |
| --- | --- | --- | | List existing audiences | `list_audiences` | Use optional fuzzy search | | Check the available Audience size or creation mode | `get_audience_limits` | Read this account’s effective limits before choosing a size | | Import supplied text research sources | `import_audience_sources` | Account-owned source import; creates no Audience | | Create an audience from a population brief or research files | `create_audience_from_brief` | Private by default; safe identical-argument retry | | Inspect a respondent dataset before cohort creation | `preview_audience_dataset_segmentation` | Enterprise workflow; never one Mind per row | | Ask one existing Audience a direct question | `ask_audience` | Creates a private one-Audience Study and submits immediately | | Refresh stored Audience grounding | `recalibrate_audience` | Refreshes grounding and recalibrates affected member profiles; `deepen` researches what the Audience still lacks; inspect returned progress | | Check an Audience against real, published surveys | `validate_audience`, `get_audience_validation` | Explicit tools, callable by name but not yet in tool discovery; needs at least 10 ready Minds; poll `get_audience_validation` with the returned `batchId` until the run settles | | List/create/ask a multi-Audience Study | `list_studies`, `create_study`, `ask_study` | Poll `get_study_status` after submission | | One direct research question | `ask_study` | Do not create a Study plan unless evidence requirements are broader | | Multiple questions, broad task, asset audit, structured outputs, or named method | `plan_study_questions` | Draft only; present every confirmation question | | Run an exact reviewed plan | `run_study_questions` | Requires explicit confirmation and exact revision | | Poll a Study | `get_study_run` | Preserve partial artifacts and plan-limit status | | Read/refresh semantic evidence summary | `get_study_summary` | `refresh: false` reads; `true` generates/refreshes | | Export existing Study evidence | `export_study` | Do not start new research | | Read/start an existing question’s asset heatmap | `study_heatmap` | Start consumes allowance; reuse the assigned asset and inspect status | | Inspect team model connection choices | `list_model_connections` | Read verified selection metadata; no credentials | | Inspect analytics | `get_study_analytics` | Preserve response-type semantics | | Resume sidebar planning state | `list_study_drafts`, `save_study_draft` | Use exact optimistic revision | | Create/chat with/export a Mind | `create_mind`, `chat_with_mind`, `export_mind` | Poll `get_mind_status` after creation | | Explicit resource lifecycle work | `manage_*` tools | Confirm destructive actions; see action matrices | ## 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 | Operation | Status tool | Terminal handling |
| --- | --- | --- | | Mind creation/training | `get_mind_status` | Chat only when ready; report failure details | | Direct Audience/Study question | `get_study_status` | Present aggregated and individual answers when complete | | Guided Study | `get_study_run` | Preserve immutable plan, method calculations, and artifacts | | Export | `export_study` then returned status/link; optionally `get_study_status` | Present artifact only when ready | | Knowledge ingestion | `manage_mind_knowledge` with `action: "status"` | Do not assume uploaded means processed | | Audience creation | `manage_audience` with `action: "get_progress"` when explicitly available | Report settled progress, not guessed elapsed-time progress | 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 | Result | Agent behavior |
| --- | --- | | Authentication required | Ask the user to reconnect OAuth or configure a bearer API key; do not loop | | Resource not found | Verify exact ID/account context; do not silently substitute a fuzzy match | | Validation error | Correct the named field and call again only if user intent is unchanged | | `plan_limited` returned by `run_study_questions` | Nothing started; explain that an upgrade/allowance change is required | | `status: plan_limited` from `get_study_run` | Partial artifacts exist; report completed and remaining questions | | Method has `executable: false` | Explain it is represented/planned and offer executable alternatives/fallbacks | | Tool returns `isError: true` | Do not present success text or fabricate structured content | | Ambiguous fuzzy match | Present candidates and ask the user to choose | ## 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. [Minds](https://getminds.ai/)© 2026 Minds. Deine Zielgruppe. KI-gestützt und transparent fundiert. In Minuten erstellt. [Minds auf X (Twitter)](https://x.com/mindsai_co) [Minds auf LinkedIn](https://www.linkedin.com/company/mindsaicompany/) [Minds auf Instagram](https://www.instagram.com/getminds.ai/)Minds ist Mitglied von [![ESOMAR](https://getminds.ai/images/newsroom/logos/esomar-logo.svg)ESOMAR](https://esomar.org/) [![GreenBook](https://getminds.ai/images/newsroom/logos/greenbook.svg)GreenBook Directory](https://greenbook.org/company/Minds) [![Insight Platforms](https://getminds.ai/images/newsroom/logos/insight-platforms.png)Insight Platforms](https://www.insightplatforms.com/platforms/minds/) [![Capterra](https://getminds.ai/images/newsroom/logos/capterra.svg)Capterra](https://www.capterra.com/p/10046203/Minds/) [![G2](https://getminds.ai/images/newsroom/logos/g2.svg)G2](https://www.g2.com/products/minds/reviews) [![CSSDA Best UX Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ux-award.png)CSSDA Best UX Design Award](https://www.cssdesignawards.com/) [![CSSDA Best Innovation Award](https://getminds.ai/images/newsroom/logos/cssda-best-innovation-award.png)CSSDA Best Innovation Award](https://www.cssdesignawards.com/) [![CSSDA Best UI Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ui-award.png)CSSDA Best UI Design Award](https://www.cssdesignawards.com/)