--- title: "Minds MCP Tools Reference" description: "[ko] Canonical Minds MCP tool reference for Audiences and Studies." canonical_url: "https://getminds.ai/mcp/ko/tools" last_updated: "2026-09-30T14:32:57.639Z" --- # Minds MCP Tools Reference 배포 설정에 따라 도구 수가 달라집니다. 일반 검색에는 23개가 표시되며 `list_model_connections`가 활성화되면 24개입니다. 등록된 정식 도구는 각각 42개 또는 43개입니다. 연결된 서버의 `tools/list` 응답을 기준으로 사용하세요. The [Minds MCP server](/mcp/overview) advertises 23–24 curated tools through ordinary `tools/list` discovery and registers 42–43 canonical tools in total. The product model is deliberately small: an **Audience** is a reusable collection of Minds, while a **Study** is the research workspace that contains one or more Audiences, questions, evidence, results, and exports. Compatibility names containing `group` or `panel` remain callable, but new integrations must use the Audience and Study 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](/mcp/agents) before autonomous use. MCP는 API가 `isPublic: true` 또는 `isLinkSharingEnabled: true`와 공유 ID를 반환한 경우에만 Study 또는 Audience 공개 링크를 제공합니다. 공유 해제 후 남은 ID는 활성 링크를 의미하지 않습니다. 반환된 URL을 수정하지 않고 사용하세요. 이름 검색은 보이는 최신 Minds, Audiences 또는 Studies를 최대 1,000개까지 확인합니다. 이전 레코드는 해당 목록 도구에서 `limit`와 `offset`으로 찾아 정확한 ID를 전달하세요. 불완전하거나 잘못된 목록 응답은 일치하는 레코드가 없다고 단정하지 않고 오류를 반환합니다. ## Curated advertised surface
Domain Tools
Minds export_mind
Audiences list_audiences , import_audience_sources , get_audience_limits , create_audience_from_brief , ask_audience , export_audience , duplicate_audience
Studies list_studies , list_model_connections , create_study , ask_study , get_study_status , export_study , duplicate_study , export_heatmap , study_heatmap
Guided research plan_study_questions , run_study_questions , get_study_run , list_research_methods , list_study_drafts , save_study_draft , list_study_templates , manage_study_template , get_study_summary
## Minds & Audiences ### list_minds Browse Minds owned by the authenticated user one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match among the newest 1,000 Minds. **Parameters:** - `searchQuery` (optional): Best fuzzy name match among the newest 1,000 Minds - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Entries to skip, default 0; use the previous result’s `nextOffset` **Example:** ```text "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 - `includeWebSearch` (optional): Set `false` to skip automatic web research; use `manual` for a strictly source-only Mind - `idempotencyKey` (optional UUID): Choose one key before creating and reuse it with the same inputs for retries, including after timeouts. Use a fresh key for another Mind. The result returns the operation key in `structuredContent.idempotencyKey`. Without an explicit key, only identical calls within 10 seconds in the same server process are coalesced; cross-process or later retries need the returned key.
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 one message to a Mind and get its response. Use `mindId` for an exact selection or `mindName` for the best fuzzy match among the newest 1,000 Minds. Browse `list_minds` by offset to find older Minds and pass their exact IDs. Use `manage_chat` for a persistent multi-turn conversation. **Parameters:** - `mindId` (optional): Mind UUID (use this OR `mindName`) - `mindName` (optional): Name with fuzzy matching (e.g., "my marketing expert") - `message` (required): Message to send - `sourcePolicy` (optional): `auto` or `knowledge_only` - `modelConnection` (optional): Verified caller-team connection ID and revision ### get_mind_status Check training progress after creating a Mind. **Parameters:** - `mindId` (required): Mind UUID ### export_mind Export a Mind profile. This tool is **Advertised**. **Parameters:** - `mindId` or `mindName`: Exact UUID or the best fuzzy name match among the newest 1,000 Minds; use an exact UUID for older Minds - `format` (optional): `md`/`markdown` (default, returned inline), `pdf`, `docx`, or `pptx` The tool polls asynchronous generation internally. A successful result includes `filename`, `mimeType`, and either inline Markdown `content` or binary `contentBase64`, plus the Mind’s workspace link. Preserve these fields when saving the export. ### list_audiences List visible Audiences one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries. **Parameters:** - `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 - `includeMinds` (optional): Include member Minds, default `false` ### create_audience Create a reusable Audience from existing Minds. **Parameters:** - `name` (required): Audience name (e.g., "Marketing Experts") - `mindIds` (required): Mind IDs to add — use `list_minds` to find IDs ### import_audience_sources 결과는 비공개이며 캐시되지 않습니다. 도구는 성공을 알리기 전에 파일 수와 순서, 소스 정책, 스냅샷 체크섬 및 분포의 소스 참조를 검증합니다. 미리보기나 생성 시 반환된 스냅샷을 변경하지 마세요. 없거나 다른 계정의 파일은 입력 오류이며, 저장소 장애는 공급자 내부 정보 없이 `502`를 반환합니다. 저장소 오류나 잘못된 확인 응답 이후에는 같은 가져오기를 재시도하세요. 내용 기반 업로드는 기존 파일을 보존합니다. The MCP HTTP request body is limited to 24 MiB, including JSON escaping and protocol fields; oversized requests return HTTP `413` with a JSON-RPC error. Source-import file and total-content limits still apply separately. `files: [{ name, content }]`로 UTF-8 `.txt`, `.md`, `.csv`, `.json` 자료를 가져옵니다. `existingFiles`와 `groundingJson`은 선택 사항입니다. 검색에 노출되는 이 도구는 Audience를 만들거나 제공된 분포를 독립 검증하지 않습니다. ### get_audience_limits 도구는 제한을 보고하기 전에 계정·팀 귀속, 숫자 상한, 중복 없는 전체 생성 모드 집합을 검증합니다. Audience별 한도 0은 데이터 누락이 아니라 워크스페이스 잠금입니다. 응답은 비공개이며 캐시되지 않습니다. 인증 정보의 차단 상태를 다시 확인하며, 이용 권한을 조회할 수 없으면 무료 플랜 한도를 임의로 반환하지 않고 `503`을 반환합니다. 규모를 선택하기 전에 이 계정의 Audience 규모 및 생성 모드 한도를 읽습니다. 선택적 `mode`로 필터링합니다. 자동 규모 한도와 명시적으로 요청한 규모 한도를 구분하세요. 이 도구는 검색에 노출됩니다. ### create_audience_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`: Audience name - `links`, `keywords`, `files`: Research context - `includeWebSearch`: Set `false` for file-only grounding - `memberCount`: Requested cohort size, subject to plan allowance - `audienceCreationMode`: `balanced`, `segment_coverage`, or `benchmark_depth` - `datasetSegmentation`: Reviewed output from `preview_audience_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 Audience. 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 same durable creation state. 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 Audience. `groundingPreview: true`로 생성 전에 프로필과 출처의 연구 결과를 검토하세요. 동일한 입력 및 `memberCount`와 함께 `reviewedGroundingJson`과 `reviewedGroundingSha256`을 변경 없이 반환합니다. 대기 중인 `structuredContent.operation`이 반환되면 해당 `jobId`를 `operationId`로 설정하고 이 인자만으로 `create_audience_from_brief`를 다시 호출합니다. 기존 작업을 이어가므로 두 번째 Audience를 생성하거나 중복 과금하지 않습니다. 완료된 결과에는 `structuredContent.preview` 또는 `structuredContent.audience`가 포함됩니다. 생성된 Audience는 웹 리서치가 백그라운드에서 계속되는 동안에도 몇 초 안에 사용할 수 있습니다. 생성된 Audience의 구조화된 `research` 필드가 이를 알려 주며(`phase: "researching"`), 작업을 다시 읽을 때는 `readiness.research`가 보고합니다. Study는 바로 실행할 수 있습니다. 출처가 있는 증거가 Audience의 명시된 가정을 자동으로 대체하고, Minds는 실행 사이에 재보정되며 실행 도중에는 재보정되지 않습니다. [2단계 생성](/docs/api/audiences)을 참고하세요. ### preview_audience_dataset_segmentation 미리보기 요청은 최대 256 KiB의 JSON을 허용합니다. 거부를 포함한 응답은 비공개이며 캐시되지 않습니다. 잘못된 JSON이나 필드는 `400`, 요청 또는 데이터셋 크기 초과는 `413`, Team 자격이나 업로드 접근 거부는 `403`을 반환합니다. 권한 정보 조회 실패는 `503`, 예상하지 못한 다운로드·분류·분석 실패는 일반적인 `500`을 반환합니다. `segmentationColumns`를 생략하면 기본 모집단 및 세분화 변수를 선택하며, 식별자가 아닌 모든 필드를 선택하지는 않습니다. MCP는 전체 집계 응답을 검증하고 행 합계, 선택 변수, 보고된 발견 수를 대조한 뒤 분석을 설명합니다. 선언되지 않은 필드는 제외합니다. 이전 응답에 관계 또는 의존성 수가 없으면 0이 아니라 미보고로 표시합니다. 이 미리보기는 원본 데이터 검토이며 코호트를 생성하거나 향후 할당을 검증하지 않습니다. 허가된 Minds 업로드는 저장소 접근 검사를 거쳐 읽습니다. Minds 호스트의 URL을 포함한 모든 네트워크 대체 다운로드는 공개 URL 보호 기능으로 리디렉션 목적지를 검증합니다. 동일 출처라도 사설 네트워크 보호를 우회하지 않습니다. 다운로드는 50 MiB 스트리밍 제한과 30초 시간 제한을 유지합니다. 실패한 HTTP 응답은 오류를 반환하기 전에 취소됩니다. 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_audience_from_brief`. ### get_audience Read an Audience's members, grounding, source metadata, sharing state, and Formations. This is an **Explicit** tool. **Parameters:** pass `audienceId` or `audienceName`. Name lookup is fuzzy, so do not call `list_audiences` first solely to resolve a natural user reference. 결과에는 Audience의 커버리지 개수(`sourced`, `proxy`, `assumed`, `missing` 차원)와 백그라운드 리서치 상태(`research`)가 표시됩니다. ### ask_audience Ask one existing Audience a direct research question. This tool is **Advertised**. It creates a private one-Audience Study, submits the question, and returns immediately; poll `get_study_status` for results. **Parameters:** - `audienceId` or `audienceName` - `question` (required) - `name` (optional): Internal Study name - `attachments` (optional): Reusable file/image context with a `url` or storage `path` Use `ask_study` when the user already has a multi-Audience Study. Each `ask_audience` call creates a new private wrapper Study. ### recalibrate_audience Refresh and replace an Audience's stored grounding from authoritative web research, then re-allocate the members' cohort profiles to match the refreshed distributions — the same distributions-to-members logic the drafting flow uses. The instruction's reach decides how deeply members change, covering demographic, psychographic, behavioral, and firmographic amendments alike: composition or evidence edits ("make men 40%", "add an income distribution") touch only members whose allocation cell actually changed; trait changes ("now they're all vegan", "SMB owners instead of enterprise buyers") make members evolve in place — same Mind, same name and portrait, rewritten role and description, knowledge retrained; population pivots ("now African consumers") rebuild every member in place — same Mind, new persona and portrait, knowledge wiped and retrained — so studies, shares, and chat history keep working while the Minds genuinely become the new audience. No Minds are deleted; retraining runs asynchronously and the Audience shows build progress until it finishes. An additive instruction ("and now add 10 African consumers") grows the roster instead: new members are generated for the added audience within the plan's member limits. While the research runs the Audience reports a **Calibrating…** state in the app and via `get_audience`. This is an **Explicit** tool and owner-only. **Parameters:** `audienceId` or `audienceName`, plus optional `instruction` for a user adjustment on top of the original brief (for example "add an income distribution"), or `query` only when the user wants to steer research away from the original brief entirely. `deepen: { topics? }`를 전달하면 도구가 Audience를 심화합니다. 커버리지가 누락 또는 가정으로 보고하는 모든 표준 차원과 지정한 최대 8개 주제(각각 120자 이하)를 리서치하고, 결과를 저장된 그라운딩에 추가하며(같은 차원에서는 더 강한 증거가 약한 증거를 대체하고 다른 모든 차트는 유지됨), 멤버를 재보정합니다. `deepen`은 `query`나 분포와 함께 사용할 수 없으며, Audience의 백그라운드 리서치가 실행 중일 때는 거부됩니다. ### list_formations 첫 페이지(`offset: 0`)에서는 대기 중인 빌드를 오래된 순서로 최대 100개까지 복구 대상으로 확인합니다. 한 번의 시도가 실패해도 선택된 다른 빌드의 시도나 목록 반환은 중단되지 않습니다. 빌드 상태를 확인하고 첫 페이지를 다시 열어 대기 중인 작업을 재시도하세요. `list_formations`와 `action: "list"`인 `manage_formation`은 선택적 `limit`, `offset`을 받습니다. 호출마다 기본·최대 100개인 한 페이지를 반환합니다. `hasMore`가 참이면 `pagination.nextOffset`으로 계속 요청하세요. `list_formations`의 `totalCount`는 표시된 개수가 아닌 전체 가시 항목 수입니다. 끝을 넘은 빈 페이지는 Audience에 Formation이 없다는 뜻이 아닙니다. 잘못된 이어받기 메타데이터는 도구 오류가 됩니다. 앱과 Study 위젯은 모든 요약 페이지를 받은 후 목록을 표시하며, 후속 요청 실패를 완전한 분류처럼 표시하지 않습니다. 볼 수 있는 모든 Audience에서 공유 Formation과 자신의 비공개 Formation을 나열할 수 있습니다. MCP는 잘못된 목록이나 누락된 구성원 수를 빈 목록 또는 0명으로 보고하지 않고 거부합니다. 수치는 `ready`에서만 확정되며 `building`과 `failed`에서는 잠정적입니다. `total: 0`인 빈 첫 페이지는 자신에게 보이는 Formation이 없다는 뜻이며, 목록을 열 때 기본 분할을 생성하는 것은 Audience 편집자에게만 적용됩니다. v1 목록 응답은 거부 응답을 포함해 비공개이며 캐시되지 않습니다. 접근 조회, 초기화 또는 목록 저장소의 예상하지 못한 오류는 일반적인 `500`을 반환합니다. List persisted Formations for an Audience. This is an **Explicit** tool. Pass `audienceId` or `audienceName`. ### export_audience Export an Audience brief through the canonical v1 API and unified branded renderer. This tool is **Advertised**. **Parameters:** - `audienceId` or `audienceName`: Exact UUID or fuzzy-matched Audience name - `format` (optional): `md`/`markdown` (default), `pdf`, `docx`, or `pptx` - `force` (optional): Regenerate instead of returning a cached artifact 도구는 원래 내보내기 작업을 폴링하며 완전한 파일이 준비된 경우에만 성공을 반환합니다. `filename`, `mimeType`, Markdown `content` 또는 바이너리 `contentBase64`를 보존하세요. 인라인 Markdown은 100,000자로 제한되며 잘린 경우 `_[truncated]_`로 표시됩니다. 취소하면 폴링이 중단됩니다. 미완료 내보내기는 오류이므로 `force=true` 없이 다시 확인하세요. ### duplicate_audience Copy an Audience through `POST /api/v1/audiences/{audienceId}/duplicate`. This tool is **Advertised**. **Parameters:** - `audienceId`: Audience to duplicate; you must be able to edit it - `name` (optional): Name of the copy; defaults to ` (copy)` - `idempotencyKey` (optional): Reuse the key a failed or timed-out call returned, so a retry cannot create a second copy Returns the new Audience in `data`, its `audienceUrl` and the `idempotencyKey`. Every member Mind is copied as a new, independent Mind with its knowledge and embeddings, together with the Audience's grounding, sources, Formations and finished validations. The copied Minds count toward the plan's Mind allowance. An Audience that is still being built is refused; retry once it is ready. ## Studies (Multi-Mind Research) ### list_model_connections 인증된 팀의 활성 모델 연결을 나열합니다. 목록에 있다는 이유만으로 검증된 연결은 아닙니다. 선택 전에 기능 플래그와 `verifiedAt`을 확인하세요. 다음 요청의 `cursor`에 `pagination.nextCursor`를 전달하세요. 선언된 연결 메타데이터와 기능 필드만 반환하며 공급자 인증 정보, 원시 프로브 결과 및 선언되지 않은 진단 정보는 제외합니다. 잘못된 응답이나 진행되지 않는 커서는 오류입니다. 연결 조회 중 예상치 못한 저장소 오류는 일반적인 `500`을 반환합니다. 연결된 서버에서 모델 연결 기능이 활성화된 경우에만 도구가 공개됩니다. ### create_study Create a Study workspace and attach one or more existing or inline Audiences. **Parameters:** - `name` (required): Study name - `audienceConfigs` (optional): New Audiences to create inline — each with `name` and `mindIds` - `audienceIds` (optional): Existing Audience IDs to attach **Example:** ```text "Create a Study called 'Brand Perception Study' with two Audiences: - 'Marketing Experts' containing my SEO and Content Marketing minds - 'Consumer Insights' containing my Gen Z and Millennial minds" ``` ### ask_study Submit exactly one standalone research question to all selected Audiences in a Study. 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 question, stimulus, and respondent-facing instructions here. For a questionnaire, survey, battery, section, cohesive question set, or any request with two or more known questions, use `plan_study_questions` once with the complete set—never call `ask_study` question by question. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `question` (required): Research question - `audienceIds` (optional): Only query specific Audiences ### list_studies List Studies with their Audience composition and question counts, one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries. **Parameters:** - `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 ### get_study_status `questionId`는 개별 응답 조회와 반환 결과를 해당 질문으로 제한합니다. Study 기록의 메타데이터는 계속 읽습니다. 실행 상태 조회는 관련된 모든 커서 페이지를 따라갑니다. 실행 목록 조회가 실패하거나 불완전하면 부분 상태를 성공으로 반환하지 않고 도구 오류를 반환합니다. Get detailed Study information including in-progress questions, completed results, and export status. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `questionId` (optional): Return one question's results - `exportKind`, `exportFormat`, `exportJobId` (optional): Use the exact kind, format and job ID returned by `export_study` to inspect that artifact Report queued, running, failed and partial work as such. A polling timeout does not authorize a new submission. ### get_study_analytics Compute statistical analytics across a Study's question history. **Returns:** - **Scale questions**: Mean, median, standard deviation, consensus, Audience rankings - **Categorical questions**: Distribution, dominant category, cross-Audience divergence - **Qualitative questions**: Theme clustering, shared themes, diversity index **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) ### export_study Export Study results as a report. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `format` (optional): `pdf` (default), `docx`, `pptx`, `csv`, `xls`, `sav`, `md`, or `markdown` - `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
sav SPSS raw-data export
md / markdown Markdown report
### duplicate_study Copy a Study through `POST /api/v1/studies/{studyId}/duplicate`. This tool is **Advertised**. **Parameters:** - `studyId`: Study to duplicate; you must be able to open it - `name` (optional): Name of the copy; defaults to ` (copy)` - `idempotencyKey` (optional): Reuse the key a failed or timed-out call returned, so a retry cannot create a second copy Returns the new Study in `data`, its `workspaceUrl` and the `idempotencyKey`. The copy keeps every question, answer, chart, heatmap, summary and finished run over the same Audiences; a schedule is copied paused. Audiences are referenced, not copied; use `duplicate_audience` to copy them. A Study with a live run is refused. ### study_heatmap `studyId` 또는 `studyName`, `messageId`, `action: "get"`(기본값) 또는 `"start"`로 히트맵을 조회하거나 시작합니다. `assetKey`는 질문에 할당된 이미지/동영상을 선택합니다. 시작에는 Premium이 필요하며 Mind당 응답 한 번을 소비합니다. 완료된 분석은 재사용합니다. 이 도구는 검색에 노출됩니다. ### 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:** - `studyId` or `studyName`: Study identifier - `messageId` (required): Completed Study message containing the website heatmap - `force` (optional): Regenerate instead of returning the cached archive ## Guided Research Planning ### plan_study_questions Create or revise one durable, versioned research-plan draft. Use it for every broader objective, questionnaire, survey, battery, section, cohesive question set, visual-asset analysis, structured research output, or named method. Put every question already known into one `request`; the planner may organize them into named modules or sections, but the agent must never create one plan or run per question. Do not use it for a standalone export or a request to show existing results differently; use `export_study` or `get_study_summary` for those requests. The free-form `request` is planner input and is not sent verbatim to Minds. The tool returns one cohesive plan with the exact proposed respondent-visible question text, named modules when useful, captured intent, main source, methods, semantic outputs, and explicit `confirmationQuestions`. The assistant must present the complete draft and 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_study_questions 명시적 승인 후에만 최신 초안 수정본을 실행합니다. 고급 방법에는 `advancedMethodOptIn: true`가 필요합니다. Conjoint, MaxDiff, NPS, top/bottom box, 핵심 동인, TURF, Gabor-Granger, Van Westendorp, Kano, 선호 순위 및 세그먼트 비교가 실행 가능합니다. 실행을 약속하기 전에 `list_research_methods`, `executable: true` 및 필수 설정을 확인하세요. If the Study-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_study_run 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_study_questions`. `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 `preparesQuestionsAtExecution: true`는 실행 시 메서드 설정에서 결정론적 질문과 응답 규격을 생성함을 뜻합니다. 템플릿에 저장된 질문이 실행되는 전체 설문 도구는 아닙니다. 잘못된 카탈로그 응답은 빈 카탈로그가 아니라 오류입니다. `includePlanned: false`는 계획 중인 메서드를 제외하지만 실험적 메서드는 실행 불가 상태와 함께 표시합니다. 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. `visual-asset-analysis`와 `recommendation-synthesis`는 실험적 카탈로그 항목으로, 해당 이름의 계획 방법으로 실행할 수 없습니다. `fallbackMethodId`는 검토할 대안이며 자동 대체 허가가 아닙니다. 이미지, 동영상, 웹사이트 연구와 에셋 히트맵은 별도로 지원됩니다. Study 질문에 이미 할당된 에셋에는 `study_heatmap`을 사용하세요. 이 카탈로그 상태가 MCP의 시각 자료 분석 불가를 뜻하지는 않습니다. ### list_study_drafts 활성 Study 초안을 나열하거나 `draftId`로 저장된 전체 계획 상태를 가져옵니다. `draft`는 저장된 단계와 리비전에서 재개할 수 있고, `starting`은 시작 절차가 진행 중임을 뜻합니다. ID 조회는 재개할 수 없는 `consumed` 완료 기록을 반환할 수도 있습니다. 잘못되거나 불완전한 API 응답은 오류이며, 빈 목록이나 저장 성공의 증거가 아닙니다. ### save_study_draft 생성할 때는 첫 요청 전에 선택적 `idempotencyKey`(앞뒤 공백 제거 후 1~200자)를 정하고 결과가 불확실하면 같은 키를 재사용하세요. 같은 키를 사용하면 새 계획 입력을 적용하지 않고 기존 저장 초안을 반환합니다. 업데이트할 때는 키를 생략하고 `draftId`와 현재 `expectedRevision`을 사용하세요. 키가 없으면 생성 요청을 반복할 때 별도 초안이 생성될 수 있습니다. 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. 기반 v1 엔드포인트는 비공개이며 캐시할 수 없는 응답을 반환합니다. 생성/업데이트 JSON 요청은 1 MiB, 버전이 있는 `payload`는 별도로 512 KiB, consume 요청은 4 KiB로 제한됩니다. 잘못된 입력은 `400`, 크기 초과는 `413`, 예상치 못한 저장소 오류는 일반적인 `500`을 반환합니다. 변경되지 않은 스냅샷은 `revision`과 `updatedAt`을 유지합니다. 저장 결과가 불확실하면 재시도 전에 저장 상태를 확인하세요. 저장 자체는 연구를 시작하지 않습니다. ### get_study_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. ### list_study_templates 응답에는 완전한 템플릿 ID, 리비전, 권한 및 유효한 설정이 포함되어야 합니다. 정확한 `templateId`로 조회하면 해당 템플릿을 반환해야 합니다. 누락되거나 잘못되거나 일치하지 않는 응답은 오류입니다. 유효한 빈 목록만 템플릿이 반환되지 않았음을 의미합니다. List owned and team-shared Study templates, or supply `templateId` to read one template including its current revision and stored configuration. This tool is **Advertised**. Reading a template does not launch research. ### manage_study_template v1 템플릿 엔드포인트는 비공개이며 캐시되지 않는 응답을 반환합니다. 저장/업데이트 JSON 본문은 1 MiB, 사용 본문은 4 KiB로 제한됩니다(초과 시 `413`). 저장된 구성의 제한은 여전히 512 KiB입니다. 잘못된 JSON이나 유효하지 않은 입력은 `400`을 반환합니다. 소유권, 리비전 또는 파일에 따른 예상된 거부는 문서화된 상태를 유지하며, 예상하지 못한 저장소/공급자 오류는 일반적인 `500`을 반환합니다. 도구는 성공을 알리기 전에 각 쓰기 확인 응답을 검증합니다. 저장/업데이트는 예상된 완전한 템플릿을, 삭제는 `success: true`를, 사용은 Study 초안을 반환해야 합니다. 사용을 재시도하면 기존 `starting` 또는 `consumed` 초안이 반환될 수 있으며, 이를 새로 편집 가능한 초안으로 안내하지 않습니다. 확인 응답이 불완전하면 재시도 전에 저장된 템플릿이나 초안을 확인하고 원래 요청 ID를 유지하세요. Save, update, use or delete a Custom Study template. This tool is **Advertised**. Set `action` to `save`, `update`, `use` or `delete`; non-save actions require `templateId`. Provide the matching `save`, `update` or `use` object for that action. Only owners can update, delete or change team sharing. Use the current revision for updates and use. Preserve `save.requestId` for retry-safe creation; `use.requestId` must be a fresh UUID for each intended draft and reused only for a retry of that same request. `use` creates an independent editable draft to finish in the web app; it never starts research. Audiences and context are entered fresh. Review changes and confirm destructive actions before executing them. ## Explicit lifecycle tools These seven registered canonical tools expose the remaining v1 research lifecycle. They are intentionally omitted from the 23–24-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 `regenerate_image`에서 기존 인물 이미지를 교체하려면 `force: true`를 전달하세요. 그렇지 않으면 이미 이미지가 있는 Mind는 건너뜁니다. 선택적 `personaContext`(앞뒤 공백 제거 후 1~16,000자)는 시스템 프롬프트를 바꾸지 않고 이미지 생성 방향을 지정합니다. API 확인 응답이 없거나 구조가 잘못되면 재시도 전에 현재 상태를 확인하라는 오류를 반환합니다. 요청이 응답했다고 해서 백그라운드 학습, 이미지 생성, 지식 수집 또는 세분화가 완료된 것은 아닙니다. 반환된 상태와 개수를 확인하세요.
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 `action: "list"`에서는 `limit`(1–100)과 `offset`(0 이상)을 선택적으로 지정합니다. 기본 페이지는 최대 100개 항목을 포함합니다. `data.pagination.hasMore`를 확인하고 offset을 늘려 다음 페이지를 가져오세요. `data.total`은 전체 개수입니다. 정렬과 일관성 제한은 [지식 페이지 조회](/docs/api/ko/knowledge)를 참고하세요. All actions require `mindId`.
Action Additional inputs Effect
list limit , offset 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_audience All actions require `audienceId`.
Action Additional inputs Effect
get — Read Audience details and grounding
get_progress — Read settled build progress
follow / unfollow — Save or unsave a visible Audience
update name , visibility/team-sharing fields as needed Update supported Audience fields
delete Explicit confirmation Delete the Audience
add_member / remove_member mindId Change Audience membership
regenerate_images Optional force , limit , dry Regenerate member images or preview the operation
### manage_formation `preview`의 `userInput`과 `priorHypothesis`는 모두 선택 사항입니다. 빈 텍스트는 기본 요청을 사용하며, 텍스트는 앞뒤 공백 제거 후 최대 2000자입니다. 전달하는 JSON은 64 KiB 이하여야 합니다. MCP는 반환된 개수, 플래그, 단계와 생성 규칙을 충족하는 가설을 검증하고 알 수 없는 필드를 제거하며 잘못된 응답에 도구 오류를 반환합니다. 미리보기는 Formation을 저장하지 않습니다. `get`에서 MCP는 반환된 Formation ID와 상세 필드를 검증하고 저장된 진단 정보를 제거하며 안전한 오류 메시지를 사용합니다. 잘못되거나 요청과 일치하지 않는 상세 응답은 도구 오류를 반환합니다. 구성원 배정을 사용하기 전에 `status`를 확인하세요. 재계산 중에도 이전에 완료된 그룹이 남아 있을 수 있습니다. `create`에는 비어 있지 않은 텍스트와 공백 제거 후 고유한 ID 및 레이블을 가진 2–15개 그룹을 검토해 제공하세요. 예약된 ID인 `unanswered`, `__unanswered`, `__other`는 사용하지 마세요. `name`은 선택 사항입니다. 전달하는 JSON은 64 KiB 이하여야 합니다. 구성원이 있는 기본 그룹이 두 개 미만인 사용자 분할은 실패하므로 사용 전에 상태를 확인하세요. 생성 오류는 [Audience API](/docs/api/audiences)를 참조하세요. All actions require `audienceId`.
Action Additional inputs Effect
list — List Formations
get formationId Read a Formation
preview userInput , 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_study Requires `studyId`. `action: "get"` reads a Study and returns its workspace link. `action: "delete"` requires explicit confirmation and deletes it. 소유자는 필수 불리언 `isLinkSharingEnabled`와 함께 `action: "set_link_sharing"`을 사용하거나, 1~100개의 `emails`와 선택적 `role`(기본값 `member` 또는 `admin`)로 `action: "invite"`를 사용할 수도 있습니다. 공개 공유는 사용자가 명시적으로 요청한 경우에만 활성화하세요. 연결된 Audiences와 Minds도 공개적으로 읽을 수 있게 됩니다. 공개 접근이 활성화되어 있으면 결과에 `sharedStudyUrl`이 포함됩니다. 초대 결과에는 `emailFailures`가 포함되며, API 성공 응답이 모든 이메일의 전달 성공을 보장하지는 않습니다. ### manage_chat
Action Required Effect
create One of mindId , mindIds , or audienceIds ; 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
기존 Study 응답을 이어가려면 `create`에 단일 `mindId`와 `responseThread: { studyId, messageId }`를 전달할 수도 있습니다. 서버는 접근이 허용된 이전 맥락과 파일을 보존합니다. ### manage_study_draft `draftId`에 초안 UUID가 필요합니다. `action: "delete"`는 초안을 삭제하며 본문이 없는 성공 API 응답이 필요합니다. `action: "consume"`에는 양수 `expectedRevision`이 필요하며 `studyId`에 Study UUID를 선택적으로 지정할 수 있습니다. 이 작업은 계획 상태를 종료하며 연구를 시작하거나 확인하지 않습니다. 활성 초안의 오래된 리비전은 거부됩니다. 이미 소비된 초안을 다시 요청하면 연결된 Study를 변경하지 않고 기존 종료 기록을 반환합니다. 도구는 해당 초안과 일치하는 `consumed` 응답을 요구하며 잘못된 확인 응답을 오류로 처리합니다. 결과가 불확실하면 재시도 전에 저장된 상태를 확인하세요. ## 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](/settings/api-keys) or through an independently authenticated REST administration flow.