---
title: "Minds MCP Tools Reference | Minds"
canonical_url: "https://getminds.ai/mcp/tools"
last_updated: "2026-08-13T13:55:56.397Z"
meta:
  description: "Reference for the curated Minds MCP tools that create audiences, plan and confirm research studies, run panels, summarize evidence, and export reports."
  "og:description": "Reference for the curated Minds MCP tools that create audiences, plan and confirm research studies, run panels, summarize evidence, and export reports."
  "og:title": "Minds MCP Tools Reference | Minds"
  "twitter:description": "Reference for the curated Minds MCP tools that create audiences, plan and confirm research studies, run panels, summarize evidence, and export reports."
  "twitter:title": "Minds MCP Tools Reference | Minds"
---

Minds

Minds Team

# **Minds MCP Tools Reference**

Reference for the curated Minds MCP tools that create audiences, plan and confirm research studies, run panels, summarize evidence, and export reports.

The [Minds MCP server](https://getminds.ai/mcp/overview) advertises 18 curated tools through ordinary `tools/list` discovery and registers 35 canonical tools in total. The additional tools cover explicit Mind, knowledge, Group, Formation, Panel, chat, and Study-draft lifecycle operations. Compatibility aliases may remain callable, but integrations should always use the canonical names documented here.

The **Advertised** label below means ordinary clients discover the tool automatically. **Explicit** means the canonical tool is registered and callable by integrations that can configure or invoke a known tool name, but it is omitted from the curated discovery surface. Read the [agent operating guide](https://getminds.ai/mcp/agents) before autonomous use.

## Curated advertised surface

| Domain | Tools |
| --- | --- |
| Minds | `export_mind` |
| Groups | `list_groups`, `create_group_from_brief`, `ask_group`, `export_group` |
| Panels | `list_panels`, `create_panel`, `ask_panel`, `get_panel_status`, `export_panel`, `export_heatmap` |
| Guided research | `plan_panel_study`, `run_panel_study`, `get_panel_study`, `list_research_methods`, `list_study_drafts`, `save_study_draft`, `get_panel_summary` |

## Minds & Groups

### list_minds

List all Minds owned by the authenticated user with optional search.

**Parameters:**

- `searchQuery` (optional): Filter by name using fuzzy search

**Example:**

```
"List my AI minds about marketing"
```

### create_mind

Create a new Mind — a synthetic expert, consumer persona, or digital twin.

**Parameters:**

- `name` (required): Name of the Mind
- `mode` (required): Training mode — `keywords`, `clone`, `link`, or `manual`
- `type` (optional): Type — `creative`, `expert`, or `user` (default: `expert`)
- `discipline` (optional): Area of expertise
- `keywords` (optional): Topics for training (required for `keywords` mode)
- `personaContext` (optional): Person to model (required for `clone` mode)
- `contextLink` (optional): URL to train from (required for `link` mode)
- `description` (optional): What this Mind specializes in

| Mode | Description | Required Fields |
| --- | --- | --- |
| `keywords` | Train from topic keywords | `keywords` |
| `clone` | Create a digital twin of a person | `personaContext` |
| `link` | Train from website content | `contextLink` |
| `manual` | Manual configuration | None |

### chat_with_mind

Send a message to a Mind and get a response. Supports multi-turn conversations and fuzzy name matching.

**Parameters:**

- `sparkId` (optional): Mind UUID (use this OR `sparkName`)
- `sparkName` (optional): Name with fuzzy matching (e.g., "my marketing expert")
- `message` (required): Message to send
- `conversationHistory` (optional): Previous messages for multi-turn context

### get_mind_status

Check training progress after creating a Mind.

**Parameters:**

- `sparkId` (required): Mind UUID

### export_mind

Export a Mind profile. This tool is **Advertised**.

**Parameters:**

- `mindId` or `mindName`: Exact UUID or fuzzy-matched name
- `format` (optional): `md`/ `markdown` (default, returned inline), `pdf`, `docx`, or `pptx`

Generated binary formats can be asynchronous. Preserve the returned filename, status, and download link.

### list_groups

List all Mind groups visible to the user.

**Parameters:**

- `searchQuery` (optional): Filter by name using fuzzy search

### create_group

Create a named group of Minds for panel research.

**Parameters:**

- `name` (required): Group name (e.g., "Marketing Experts")
- `sparkIds` (required): Mind IDs to add — use `list_minds` to find IDs

### create_group_from_brief

Create a grounded synthetic audience from a population brief, source links, keywords, and research files. This tool is **Advertised** and private by default.

Important parameters include:

- `brief` (preferred) or legacy `text`: Population description
- `name`: Group name
- `links`, `keywords`, `files`: Research context
- `includeWebSearch`: Set `false` for file-only grounding
- `memberCount`: Requested cohort size, subject to plan allowance
- `groupCreationMode`: `balanced`, `segment_coverage`, or `benchmark_depth`
- `datasetSegmentation`: Reviewed output from `preview_group_dataset_segmentation`
- `cohortAllocation`: Deterministic marginal/joint allocation configuration
- `isLinkSharingEnabled`: Enable only after an explicit request for a public link

Identical arguments are idempotent for approximately six hours. After a timeout, retry the same arguments to recover the original Group. Deeper creation modes are Team-plan workflows; inspect the effective mode returned by the server rather than assuming the request was accepted unchanged.

While creation runs, every open workspace for the authenticated owner is notified through the user-scoped lifecycle stream and re-reads the shared durable GroupDraft ledger. The UI therefore displays the same Drafting, Creating, and Ready states for UI, REST, and MCP creation. Repeating identical arguments reuses that lifecycle instead of duplicating the Group.

### preview_group_dataset_segmentation

Inspect a CSV, XLS, or XLSX respondent dataset before representative cohort creation. This is an **Explicit** Enterprise workflow.

**Parameters:**

- `file.name`: Original spreadsheet filename
- `file.url`: Public, signed, or Minds workspace-upload URL
- `segmentationColumns` (optional): Reviewed column keys from a previous preview

The tool classifies file content, uses all completed respondent rows, identifies structural versus held-out variables, and recommends a representative Mind count. It never creates one Mind per respondent. Screeners and questionnaire programming grids are rejected as respondent data and should be passed directly to `create_group_from_brief`.

### get_group

Read a Group's members, grounding, source metadata, sharing state, and Formations. This is an **Explicit** tool.

**Parameters:** pass `groupId` or `groupName`. Name lookup is fuzzy, so do not call `list_groups` first solely to resolve a natural user reference.

### ask_group

Ask one existing Group a direct research question. This tool is **Advertised**. It creates a private one-Group Panel, submits the question, and returns immediately; poll `get_panel_status` for results.

**Parameters:**

- `groupId` or `groupName`
- `question` (required)
- `name` (optional): Internal Panel name
- `attachments` (optional): Reusable file/image context with a `url` or storage `path`

Use `ask_panel` when the user already has a multi-Group Panel. Each `ask_group` call creates a new private wrapper Panel.

### recalibrate_group

Refresh and replace a Group's stored grounding from authoritative web research without changing its members. This is an **Explicit** tool and owner-only.

**Parameters:** `groupId` or `groupName`, plus optional `query` only when the user wants to steer research away from the original brief.

### list_formations

List persisted Formations for a Group. This is an **Explicit** tool. Pass `groupId` or `groupName`.

### export_group

Export a Group brief through the canonical v1 API and unified branded renderer. This tool is **Advertised**.

**Parameters:**

- `groupId` or `groupName`: Exact UUID or fuzzy-matched Group name
- `format` (optional): `md`/ `markdown` (default), `pdf`, `docx`, or `pptx`
- `force` (optional): Regenerate instead of returning a cached artifact

## Panels (Multi-Mind Research)

### create_panel

Create a research panel that groups multiple Minds for comparative analysis.

**Parameters:**

- `name` (required): Name for the panel
- `groupConfigs` (optional): New groups to create inline — each with `name` and `sparkIds`
- `groupIds` (optional): Existing group IDs to attach

**Example:**

```
"Create a panel called 'Brand Perception Study' with two groups:
 - 'Marketing Experts' containing my SEO and Content Marketing minds
 - 'Consumer Insights' containing my Gen Z and Millennial minds"
```

### ask_panel

Submit one direct research question to all groups in a panel. Treat the entire `question` value as respondent-visible input. The system may classify or reformat it, but any text in this field can reach the selected Minds and influence their answers. Put only the concept, question, and instructions intended for the Minds here; keep planner or MCP-client notes outside it. Likely behavioural framing produces a non-blocking warning because it may influence results. Questions are automatically classified as scale, categorical, or qualitative. For multiple questions, a broader task, an asset audit, structured outputs, or an explicit method, use `plan_panel_study` first.

**Parameters:**

- `panelId` (optional): Panel UUID
- `panelName` (optional): Panel name (fuzzy matched)
- `question` (required): Research question
- `groupIds` (optional): Only query specific groups

### list_panels

List all research panels with group composition and question counts.

**Parameters:**

- `searchQuery` (optional): Filter by name using fuzzy search

### get_panel_status

Get detailed panel information including in-progress questions, completed results, and export status.

**Parameters:**

- `panelId` (optional): Panel UUID
- `panelName` (optional): Panel name (fuzzy matched)

### get_panel_analytics

Compute statistical analytics across a panel's question history.

**Returns:**

- **Scale questions**: Mean, median, standard deviation, consensus, group rankings
- **Categorical questions**: Distribution, dominant category, cross-group divergence
- **Qualitative questions**: Theme clustering, shared themes, diversity index

**Parameters:**

- `panelId` (optional): Panel UUID
- `panelName` (optional): Panel name (fuzzy matched)

### export_panel

Export panel results as a report.

**Parameters:**

- `panelId` (optional): Panel UUID
- `panelName` (optional): Panel name (fuzzy matched)
- `format` (optional): `pdf` (default), `docx`, `pptx`, `csv`, `xls`, or `md`
- `kind` (optional): `executive_brief`, `full_report` (default), or `raw_data`
- `length` (optional): `brief`, `standard`, or `detailed`
- `force` (optional): Regenerate instead of returning a cached artifact

| Format | Description |
| --- | --- |
| `pdf` | Branded PDF report |
| `docx` | Editable Word report |
| `pptx` | Editable presentation |
| `csv` | CSV workbook export |
| `xls` | Excel workbook export |
| `md` / `markdown` | Markdown report |

### export_heatmap

Export a completed website heatmap as the same ZIP archive available in the web app. The archive includes a unified-renderer PDF report, Markdown, source images, and metadata. This tool is **Advertised**.

**Parameters:**

- `panelId` or `panelName`: Panel identifier
- `messageId` (required): Completed Panel message containing the website heatmap
- `force` (optional): Regenerate instead of returning the cached archive

## Guided Research Planning

### plan_panel_study

Create or revise a durable, versioned research-plan draft. This tool is model-aware: it must be called before broader or multi-question research, visual-asset analysis, structured outputs that are part of a new study, or optional methods. Do not use it for a standalone export or a request to show existing results differently; use `export_panel` or `get_panel_summary` for those requests.

The free-form `request` is planner input and is not sent verbatim to Minds. The tool returns the exact proposed respondent-visible question text, captured intent, main source, methods, semantic outputs, and explicit `confirmationQuestions`. The assistant must present those questions—including any framing warning—and must not claim the research has started. If the user changes anything, call the tool again with `draftPlanId` and `revision`.

### run_panel_study

Confirm and run the exact latest draft revision. Call it only after explicit user confirmation; silence and agent-suggested defaults are not consent. Advanced methods require `advancedMethodOptIn: true`, but only catalog entries with `executable: true` can run. MaxDiff, NPS, top/bottom box, key drivers, TURF, Gabor-Granger, Van Westendorp, Kano, ranked preferences, and segment comparison are executable through their registered server adapters; Conjoint is planned and does not execute through this tool yet.

If the Panel-answer allowance is already exhausted, the tool returns a structured `plan_limited` error and the study does not start. Tell the user plainly that an upgrade is required; do not describe the survey as queued or completed.

### get_panel_study

Read durable status, question progress, the immutable confirmed plan, the separate server-prepared execution plan, the exact respondent-visible question audit, method stages, response artifacts, and deterministic method calculations for a study started by `run_panel_study`.

`plan_limited` means an in-progress survey stopped before all questions completed. Preserve its partial artifacts, state how many questions completed, and tell the user to upgrade before starting a follow-up run for the remainder.

### list_research_methods

List versioned methods with `executable`, availability, complexity, configuration requirements, semantic outputs, and fallbacks. Use this when the user explicitly asks for MaxDiff, NPS, Kano, TURF, pricing methods, Conjoint, or methodological options. A represented method is not necessarily runnable; only `executable: true` is an execution promise. Keep the default workflow simple when users do not ask for methodological complexity.

### list_study_drafts

List durable, resumable study drafts or retrieve one complete saved planning state by `draftId`. These drafts have not started; use the returned current step and revision to resume the exact planning flow.

### save_study_draft

Create or revise a durable Study planning draft without starting research. A revision requires the exact `draftId` and `expectedRevision`; the tool saves a closed set of planning inputs into the same versioned Custom planner state used by the Minds sidebar.

### get_panel_summary

Retrieve the persisted semantic summary, or refresh it when `refresh: true`. Blocks are flexible evidence descriptors rather than fixed UI components. Preserve heatmap outputs for website, image, ad, and video analysis.

## Explicit lifecycle tools

These seven registered canonical tools expose the remaining v1 research lifecycle. They are intentionally omitted from the 15-tool curated discovery list until their product presentation is reviewed. An integration that calls one explicitly must supply the canonical schema and honor destructive/confirmation annotations.

### manage_mind

| Action | Required | Effect |
| --- | --- | --- |
| `get` | `mindId` | Read one Mind |
| `update` | `mindId` | Update supported `name`, `description`, `discipline`, `systemPrompt`, `sourcePolicy`, `tags`, or sharing state |
| `delete` | `mindId`, explicit confirmation | Delete one Mind through canonical cleanup |
| `delete_many` | `mindIds` (1–100), explicit confirmation | Batch-delete confirmed Minds and report independent outcomes |
| `retrain` | `mindId` | Queue retraining with a complete stored knowledge-index rebuild |
| `regenerate_image` | `mindId` | Regenerate the profile image |
| `regenerate_prompt` | `mindId` | Regenerate the system prompt |
| `regenerate_embeddings` | `mindId` | Queue a full rebuild of the stored knowledge vectors |
| `get_training` | `mindId` | Read training status |
| `get_patterns` | `mindId` | Read raw patterns when permitted |

### manage_mind_knowledge

All actions require `mindId`.

| Action | Additional inputs | Effect |
| --- | --- | --- |
| `list` | — | List items |
| `add` | One of `link`, `keywords`, or `file`; optional `description`, `regeneratePrompt` | Queue knowledge ingestion |
| `update` | `itemId` and supported fields | Update an item |
| `delete` | `itemId`, explicit confirmation | Delete an item |
| `status` | `itemId` | Read processing status |
| `enrich` | `keywords` | Run keyword enrichment |
| `patterns` | — | Read knowledge patterns |

`file` has `{ name, url, type? }`. The URL must be public, short-lived signed, or a Minds workspace-upload URL. Retrieval is SSRF-guarded, time-bounded, and limited to 50 MB; do not embed base64 binary data.

### manage_group

All actions require `groupId`.

| Action | Additional inputs | Effect |
| --- | --- | --- |
| `get` | — | Read Group details and grounding |
| `get_progress` | — | Read settled build progress |
| `follow` / `unfollow` | — | Save or unsave a visible Group |
| `update` | `name`, visibility/team-sharing fields as needed | Update supported Group fields |
| `delete` | Explicit confirmation | Delete the Group |
| `add_member` / `remove_member` | `mindId` | Change Group membership |
| `regenerate_images` | Optional `force`, `limit`, `dry` | Regenerate member images or preview the operation |

### manage_formation

All actions require `groupId`.

| Action | Additional inputs | Effect |
| --- | --- | --- |
| `list` | — | List Formations |
| `get` | `formationId` | Read a Formation |
| `preview` | `userInput`; optional `priorHypothesis` | Return a non-persisted JSON hypothesis |
| `create` | `name`, reviewed `hypothesis` | Persist and compute a Formation |
| `delete` | `formationId`, explicit confirmation | Delete a Formation |
| `recompute` | `formationId` | Recompute assignments |

A hypothesis contains `intent` and `subgroups[]` with `id`, `label`, and `definition`. The UI consumes NDJSON progress and this tool requests JSON from the same v1 preview endpoint.

### manage_panel

Requires `panelId`. `action: "get"` reads a Panel and returns its workspace link. `action: "delete"` requires explicit confirmation and deletes it.

### manage_chat

| Action | Required | Effect |
| --- | --- | --- |
| `create` | One of `mindId`, `mindIds`, or `groupIds`; optional `name`, `description` | Create a stateful chat |
| `send_message` | `chatId`, `message`; optional `role` | Append a message and get the next response |
| `delete` | `chatId`, explicit confirmation | Delete chat history |

### manage_study_draft

Requires `draftId`. `action: "delete"` deletes a confirmed draft. `action: "consume"` requires the exact positive `expectedRevision` and accepts an optional `panelId`; stale revisions are rejected.

## Deliberate exclusions

API credential creation, rotation, and revocation are not exposed through MCP because an MCP session must not control its own bearer credential. Manage keys only in authenticated [account settings](https://getminds.ai/settings/api-keys) or through an independently authenticated REST administration flow.