---
title: "Minds MCP Operating Guide for AI Agents | Minds"
canonical_url: "https://getminds.ai/mcp/agents"
last_updated: "2026-08-13T13:01:02.868Z"
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.

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

- **15 advertised tools** are returned by ordinary `tools/list` discovery.
- **35 canonical tools** are registered across Minds, Groups, Panels, Studies, 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 15 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_groups` | Use optional fuzzy search |
| Create an audience from a population brief or research files | `create_group_from_brief` | Private by default; safe identical-argument retry |
| Inspect a respondent dataset before cohort creation | `preview_group_dataset_segmentation` | Enterprise workflow; never one Mind per row |
| Ask one existing Group a direct question | `ask_group` | Creates a private one-Group Panel and submits immediately |
| Refresh stored Group grounding | `recalibrate_group` | Replaces grounding; members remain unchanged |
| List/create/ask a multi-Group Panel | `list_panels`, `create_panel`, `ask_panel` | Poll `get_panel_status` after submission |
| One direct research question | `ask_panel` | Do not create a Study plan unless evidence requirements are broader |
| Multiple questions, broad task, asset audit, structured outputs, or named method | `plan_panel_study` | Draft only; present every confirmation question |
| Run an exact reviewed plan | `run_panel_study` | Requires explicit confirmation and exact revision |
| Poll a Study | `get_panel_study` | Preserve partial artifacts and plan-limit status |
| Read/refresh semantic evidence summary | `get_panel_summary` | `refresh: false` reads; `true` generates/refreshes |
| Export existing Panel evidence | `export_panel` | Do not start new research |
| Inspect analytics | `get_panel_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_panel_study
  -> show the captured objective, main source, questions, methods, and outputs
  -> ask every returned confirmation question
  -> call plan_panel_study again with answers/refinements
  -> obtain explicit confirmation of the exact draft ID and revision
  -> run_panel_study with confirmed: true
  -> poll get_panel_study
  -> read or refresh get_panel_summary
```

Rules:

- A planning response is not an executed Study.
- 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, Group, Panel, 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 Groups and Panels are private unless `isLinkSharingEnabled: true` is passed.
- Set that flag only when the user explicitly requests a public/shareable link.
- A shared Group 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_group`, `get_group`, `recalibrate_group`, and `list_formations` can resolve a Group name directly. Do not insert a redundant list call solely for lookup.
- Panel tools may use the active Panel from the MCP session when both ID and name are omitted. For durable/multi-user automation, pass the explicit `panelId`.
- 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 Group/Panel question | `get_panel_status` | Present aggregated and individual answers when complete |
| Guided Study | `get_panel_study` | Preserve immutable plan, method calculations, and artifacts |
| Export | `export_panel` then returned status/link; optionally `get_panel_status` | Present artifact only when ready |
| Knowledge ingestion | `manage_mind_knowledge` with `action: "status"` | Do not assume uploaded means processed |
| Group creation | `manage_group` with `action: "get_progress"` when explicitly available | Report settled progress, not guessed elapsed-time progress |

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_group_from_brief` is idempotent for identical arguments. Retry the exact same payload after a timeout to recover the original Group.
- To intentionally create another Group 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_group_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_group_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_panel_study` | Nothing started; explain that an upgrade/allowance change is required |
| `status: plan_limited` from `get_panel_study` | 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 Panel question headings, bold Group 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"`, `groupId`, 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, Group, Panel, 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.