> ## Documentation Index
> Fetch the complete documentation index at: https://greatquestion.co/support/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP: What's available
> Every tool call the Great Question MCP server exposes, and the security and data-handling model behind it.
The MCP provides access across the full research workflow:
**Candidates:** Create, update, and delete participant profiles. View full profiles with demographics and participation history. Search by name, email, study, date, or saved segment.
**Study design:** Create, update, and delete interview studies (1:1, round robin, or collective), survey studies, and unmoderated studies (prototype tests, website tests, card sorts, and tree tests). Configure incentives, participation caps, consent forms, participant language, and meeting providers. Build and manage screener questionnaires with qualification rules, disqualification rules, and skip logic across a full range of question types — or apply one of your saved templates instead of rebuilding questions from scratch. Add and reorder unmoderated study blocks (the tasks and questions participants work through).
**Scheduling:** Configure interview booking limits, availability windows, buffers, scheduling notice, and livestream settings. Add, update, and remove moderators, collaborators, and observers.
**Recruitment:** Shortlist existing candidates directly onto a study, or send screener invitations to qualify them first. Customize the invitation, screener, reminder, and other study emails before you send. Works across interview, survey, and unmoderated studies.
**Analysis:** Browse and search sessions, transcripts, highlights, and participant responses (screener responses for interviews; survey and unmoderated submissions for surveys and unmoderated studies). Access speaker-attributed transcripts, including session recording transcripts surfaced directly on unmoderated responses, full-text search across transcript content, and prototype-test analytics (completion rate, top response paths, and drop-off by screen) with deep-links to heatmap and funnel views.
**Synthesis:** Browse and search insights, research findings, and curated highlight reels across studies.
## Available tool calls
The MCP exposes the following tools, organized by research workflow stage. Write tools can create, update, and delete resources. Read tools retrieve and search data.
### Candidate tools
| Tool | What it does |
| :------------------ | :---------------------------------------------------------------------------------------------------------- |
| `create_candidate` | Create a new participant profile. If the email already exists, returns the existing candidate. |
| `update_candidate` | Update a participant’s profile and custom attributes. |
| `delete_candidate` | Permanently forget a candidate (irreversible). Use for GDPR compliance. |
| `get_candidate` | Get a full candidate profile by ID, including demographics and participation history. |
| `list_candidates` | Browse all participants. Returns name, email, demographics, and participation history. Supports pagination. |
| `search_candidates` | Find participants by name/email, study ID, saved segment, or updated-since timestamp. |
You can also browse and search your account's saved candidate segments (`list_candidate_segments`, `get_candidate_segment`, `search_candidate_segments`) and pass a segment ID into `search_candidates` to pull everyone matching that segment.
### Study tools (all types)
These tools work across all study types (interviews, surveys, and unmoderated studies).
| Tool | What it does |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------- |
| `get_study` | Get full details for a specific study by ID, including methodology and configuration. |
| `list_studies` | Browse all studies in your workspace. Returns title, status, style, and configuration. Supports pagination. |
| `search_studies` | Find studies by title, status (draft/active/closed), duration, creation date, last activity date, or last updated date. |
### Configuring study setup
When creating or updating any study type, you can configure:
* **Incentives:**
* incentive\_method (manual, tremendous, coupon, product, other)
* incentive (amount in whole currency units)
* currency (ISO 4217 code, e.g. USD, GBP)
* incentive\_title
* incentive\_instructions
* incentive\_coupons (codes, when the method is coupon)
* **Participation caps:** participation\_limit to cap how many people can participate
* interview studies accept an object with count and cadence (total or weekly);
* surveys and unmoderated studies accept an integer (total only).
* **Consent form:** consent\_form\_id to attach a consent form (discover IDs with list\_consent\_forms / search\_consent\_forms).
* **Participant language:** language for emails, booking pages, and public participation surfaces (de, en, es, fr, it, pt-BR, tr; defaults to en).
Interview studies additionally support:
* **Scheduling style:** scheduling\_style (one\_on\_one, round\_robin, or collective)
* with round\_robin\_assignment (availability or fairness) when using round robin.
* **Meeting provider:** meeting provider (manual, zoom, google\_meet, microsoft\_teams, webex, in\_person) and duration\_in\_minutes.
* **Calendar & availability:** availability (weekly hours, timezone, and booking window), booking\_limit (per day / per week), buffer\_minutes, and minimum/maximum scheduling notice.
**Screener question types.** Screener and survey questions across all study types support these types: short\_text, long\_text, number, number\_range, single\_choice, multiple\_choice, yes\_no, email, website, info, date, location, and matrix. Choice questions support qualifying answers, disqualifying answers, and skip logic.
### Interview study tools
Study management:
| Tool | What it does |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_interview_study` | Create a new interview study (1:1, round robin, or collective) with optional screener and skip logic. Supports incentive setup, participation caps (total or weekly), meeting provider, calendar/availability configuration, consent form, and language. |
| `update_interview_study` | Update title, goal, team, owner, scheduling style, meeting provider, calendar/availability, incentive setup, participation caps, consent form, and language. |
| `delete_interview_study` | Soft-delete an interview study. |
| `get_interview_study` | Get full interview study details by ID. |
| `list_interview_studies` | Browse all interview studies. Supports pagination. |
| `search_interview_studies` | Filter by status, creator, owner, or dates. |
### Screeners
| Tool | What it does |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `create_interview_screener` | Add or replace all screener questions on an interview study. |
| `delete_interview_screener` | Remove the screener from an interview study. |
| `get_interview_screener` | Get all screener questions and configuration. |
| `add_interview_screener_question` | Add a screener question with qualification, disqualification, and skip logic rules. Appends to existing questions. |
| `update_interview_screener_question` | Edit a question or its logic rules. |
| `delete_interview_screener_question` | Remove a screener question. |
### Survey study tools
Study management:
| Tool | What it does |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_survey_study` | Create a new survey study, optionally with its questions in a single call. Supports incentive setup, a total participation cap, consent form, and language. Screener (qualification) questions are managed separately. |
| `update_survey_study` | Update title, goal, team, ownership, incentive setup, participation cap, consent form, and language. |
| `delete_survey_study` | Soft-delete a survey study. |
| `get_survey_study` | Get full survey study details by ID. |
| `list_survey_studies` | Browse all survey studies. Supports pagination. |
| `search_survey_studies` | Filter by status, creator, owner, or dates. |
### Screeners
| Tool | What it does |
| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `create_survey_screener` | Add or replace all screener questions on a survey study. |
| `delete_survey_screener` | Remove the screener from a survey study. |
| `get_survey_screener` | Get all screener questions and configuration. |
| `add_survey_screener_question` | Add a screener question with qualification, disqualification, and skip logic rules. Appends to existing questions. |
| `update_survey_screener_question` | Edit a question or its logic rules. |
| `delete_survey_screener_question` | Remove a screener question. |
### Unmoderated study tools
Unmoderated studies cover self-guided research, prototype tests, website tests, card sorts, and tree tests. Each study is built from an ordered set of **blocks** (the tasks and questions a participant works through).
Study management:
| Tool | What it does |
| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_unmoderated_study` | Create a new unmoderated study with optional screener. Supports incentive setup, a total participation cap, consent form, and language. |
| `update_unmoderated_study` | Update title, goal, team, ownership, incentive setup, participation cap, consent form, and language. |
| `delete_unmoderated_study` | Soft-delete an unmoderated study. |
| `get_unmoderated_study` | Get full unmoderated study details by ID, including its ordered block configuration. Prototype-test blocks also return analytics (completion rate, top response paths, drop-off by screen) and deep-links to the heatmap and funnel views in the app. |
| `list_unmoderated_studies` | Browse all unmoderated studies. Supports pagination. |
| `search_unmoderated_studies` | Filter by status, creator, owner, or dates. |
### Blocks
| Tool | What it does |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_unmoderated_block` | Add a task or question block — prototype test, website test, card sort, tree test, or a question block (short/long text, number, date, location, etc.). Structural blocks (welcome, thank you, permissions, AI-moderated interview) are created with the study. |
| `update_unmoderated_block` | Update a block’s shared attributes and its kind-specific fields (e.g. prototype/website URL, card sort cards and categories, tree test nodes, permission requirements). |
| `reorder_unmoderated_block` | Move a block to a new position. Structural blocks stay pinned at the start and end. |
| `delete_unmoderated_block` | Remove a block. Structural blocks cannot be removed. |
### Screeners
| Tool | What it does |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `create_unmoderated_screener` | Add or replace all screener questions on an unmoderated study. |
| `delete_unmoderated_screener` | Remove the screener from an unmoderated study. |
| `get_unmoderated_screener` | Get all screener questions and configuration. |
| `add_unmoderated_screener_question` | Add a screener question with qualification, disqualification, and skip logic rules. Appends to existing questions. |
| `update_unmoderated_screener_question` | Edit a question or its logic rules. |
| `delete_unmoderated_screener_question` | Remove a screener question. |
### Scheduling tools
Interview calendar:
| Tool | What it does |
| :----------------------------------- | :------------------------------------------------------------------------------------------- |
| `update_interview_calendar_settings` | Configure booking limits, availability, buffers, livestream settings, and scheduling notice. |
| `get_interview_calendar_settings` | View current booking settings for an interview study. |
### Interview moderators
| Tool | What it does |
| :--------------------------- | :---------------------------------------------------------------- |
| `add_interview_moderator` | Add a moderator, collaborator, or observer to an interview study. |
| `update_interview_moderator` | Change a team member’s role or calendar settings. |
| `remove_interview_moderator` | Remove a team member from the interview study. |
| `list_interview_moderators` | View all assigned team members. |
### Study message tools
Customize the emails a study sends, invitations, screener invites, reminders, booking confirmations, thank-yous, and more, before you send them. Templates are your account's per-kind defaults; messages are the per-study copies you compose from them.
| Tool | What it does |
| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_message_templates` / `get_message_template` | Browse your account's default message templates, or fetch the default for a given kind (invite, screener, reminders, booked, thanks, welcome, and more). |
| `list_study_messages` / `get_study_message` | Browse or fetch a study's persisted messages. |
| `compose_study_message` | Compose a custom message for a study (subject, body, sender, layout). |
| `revise_study_message` | Edit an existing study message in place. |
| `discard_study_message` | Discard a custom study message. |
### Participant tools
Tools for adding candidates to a study. Shortlisting adds existing candidates to the study's participant list; sending a screener invitation emails them to fill out the study's screener. You can combine them (shortlist candidates first, then optionally send them a screener to qualify) or use either on its own.
**Shortlist existing candidates.** Each call automatically skips candidates who are already on the study, inaccessible to your team, uncontactable, or ineligible.
| Tool | What it does |
| :---------------------------- | :------------------------------------------------------------------------------------------------------ |
| `add_study_participant` | Shortlist candidates onto any study type by study ID (works across interview, survey, and unmoderated). |
| `add_interview_participant` | Shortlist candidates onto an interview study. |
| `add_survey_participant` | Shortlist candidates onto a survey study. |
| `add_unmoderated_participant` | Shortlist candidates onto an unmoderated study. |
**Send a screener invitation.** Email candidates a link to fill out the study's screener. Works whether or not they've already been shortlisted.
| Tool | What it does |
| :------------------------------------- | :----------------------------------------------------------------- |
| `send_interview_screener_invitation` | Send a screener invitation to candidates for an interview study. |
| `send_survey_screener_invitation` | Send a screener invitation to candidates for a survey study. |
| `send_unmoderated_screener_invitation` | Send a screener invitation to candidates for an unmoderated study. |
### Session & Transcript tools
| Tool | What it does |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `list_repo_sessions` | Browse all sessions (interviews, calls, observations). Returns title, summary, and timestamps. Supports pagination. |
| `search_repo_sessions` | Find sessions by title, candidate IDs, creator IDs, or study IDs. |
| `get_repo_session` | Get full session details by UUID, including tags, recording link and metadata, and associated study/candidate. |
| `get_repo_session_transcript` | Get the complete speaker-attributed transcript for a session. |
| `list_transcripts` | Browse all transcripts. Returns metadata and content. Supports pagination. |
| `search_transcripts` | Full-text search within transcript content. Filter by candidate IDs or study IDs. |
| `get_transcript` | Get a complete transcript by ID with speaker attribution. |
### Response tools
Access participant responses across all three study types. What a "response" contains depends on the study type:
* **Interview studies:** screener responses, the candidate's answers to the screener questions, with qualification status and match score. The interview session itself is accessed via the Session & Transcript tools.
* **Survey studies:** the full survey submission, the participant's answers to the survey questions.
* **Unmoderated studies**: the full submission, answers, task metrics, timings, and recording link from the recorded session, with a pointer to the session transcript included on the response.
| Type | Tool | What it does |
| :---------- | :----------------------------- | :--------------------------------------------------------------------------- |
| Interviews | `get_interview_response` | Get a participant's screener answers, match score, and qualification status. |
| | `list_interview_responses` | Browse all screener responses. Supports pagination. |
| | `search_interview_responses` | Filter screener responses by submission date. |
| Surveys | `get_survey_response` | Get a participant's survey answers and qualification status. |
| | `list_survey_responses` | Browse all survey responses. Supports pagination. |
| | `search_survey_responses` | Filter survey responses by submission date. |
| Unmoderated | `get_unmoderated_response` | Get a participant's submission with answers, task metrics, and timings. |
| | `list_unmoderated_responses` | Browse all unmoderated responses. Supports pagination. |
| | `search_unmoderated_responses` | Filter unmoderated responses by submission date. |
Screener responses are also available per study type via the dedicated screener-response tools (e.g. `get_interview_screener_response`, `list_survey_screener_responses`, `search_unmoderated_screener_responses`).
### Artifact tools (Highlights, Insights & Reels)
| Type | Tool | What it does |
| :------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| **Highlights** | `list_repo_highlights` | Browse all highlights (annotated excerpts from sessions). Returns text, title, and color. Supports pagination. |
| | `search_repo_highlights` | Find highlights by title/text, candidate IDs, creator IDs, or study IDs. |
| | `get_repo_highlight` | Get full highlight details by UUID, including description, tags, and session reference. Does not return playable video URLs. |
| **Insights** | `list_repo_insights` | Browse all insights (research findings and stories). Returns title, description, and content type. Supports pagination. |
| | `search_repo_insights` | Find insights by title/description, creator IDs, or study IDs. |
| | `get_repo_insight` | Get full insight details by slug, including text, cover image, tags, and associated study. |
| **Reels** | `list_repo_reels` | Browse all reels (curated highlight video compilations). Returns title and subtitle. Supports pagination. |
| | `search_repo_reels` | Find reels by title/subtitle, creator IDs, or study IDs. |
| | `get_repo_reel` | Get full reel details by token, including clips and tags. Does not return playable video URLs. |
`get_repo_highlight` and `get_repo_reel` do not return playable video or thumbnail URLs, at the reel level or per clip. To reach recording content, use `get_repo_session` and `get_repo_session_transcript` on the referenced session. Candidate names on these responses are masked for consumers without team access to the candidate or without PII permission, matching the masking applied elsewhere in the API.
### Template tools
Reuse your account's saved screener templates instead of rebuilding questions from scratch every time.
| Tool | What it does |
| :------------------------------------ | :----------------------------------------------------------------------------------------------- |
| `list_templates` | Browse all saved templates. Supports pagination. |
| `search_templates` | Find templates by kind (survey or interview). Each result reports how many questions it carries. |
| `get_template` | Get a single template by ID, including its full list of questions. |
| `apply_interview_screener_template` | Copy a template's questions onto an interview study's screener. |
| `apply_survey_screener_template` | Copy a template's questions onto a survey study's screener. |
| `apply_unmoderated_screener_template` | Copy a template's questions onto an unmoderated study's screener. |
Note: Applying a template replaces all existing questions on that screener, it doesn't merge or append. If you want to keep existing questions, add to the screener with the type-specific add\_\*\_screener\_question tools instead.
### Workspace tools
A few helpers surface the building blocks you reference when setting up studies:
* **Teams** (`list_teams`, `get_team`, `search_teams`) — your account's teams; pass a team ID when creating or assigning a study.
* **Consent forms** (`list_consent_forms`, `search_consent_forms`) — consent forms available to attach to a study via consent\_form\_id.
* **Candidate segments** (`list_candidate_segments`, `get_candidate_segment`, `search_candidate_segments`) — saved candidate filters; use a segment ID with search\_candidates.
#### Common tool call parameters
Most list and search tools support these options:
* **Pagination:** `page` (default 1), `items` (default 20, max 100), `cursor` for continued pagination
* **Sorting:** `orderBy` — sort by `createdAt` or `updatedAt` (default)
* **Date filtering:** Exact time windows or relative durations
## Security & data handling
| | |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authentication** | OAuth 2.1 with PKCE for human-driven clients, no secrets stored on your device. Agents connecting on their own use a secure API token instead: issued once, then used automatically in the background without further logins. |
| **Permissions** | Respects your existing Great Question access controls. You only see what you can already see in the product. |
| **Data scope** | Read and write over text-based data. The MCP can create, update, and delete candidates, studies, screeners, blocks, moderators, study messages, and participant shortlists, and can send screener invitations. No video, audio, or biometric data is transferred — recordings remain in the Great Question product. |
| **Data freshness** | Real-time. Queries hit the live API, not a cached or synced copy. |
| **Retention** | Response content is not stored or cached by default. Request metadata is retained per Great Question's existing policies. |
| **Third parties** | The MCP server runs on Great Question's infrastructure. No additional third-party processors are introduced. Once data is returned to your MCP client, it's handled by that client's data policies. |
For full privacy details, see our [Privacy Policy](https://greatquestion.co/about/privacy)
## Troubleshooting
**Permission errors?** The MCP respects your existing Great Question access controls. If you can't see certain studies or sessions, check your permissions in the Great Question product.