The Model Context Protocol lets an AI agent discover research tools and their input schemas. Your integration supplies the client connection and workflow context; User Intuition supplies planning, recruitment, interviews, and reports.
Use MCP for interactive agent orchestration. Use the public REST API when your software already knows which endpoint it needs. Both require an explicit plan for approval, completion handling, and evidence retrieval.
Connect your agent
Use the hosted endpoint, https://mcp.userintuition.ai/mcp, with OAuth in compatible clients. For local stdio, run npx -y @userintuition-ai/mcp with USERINTUITION_API_KEY set to your ui_sk_ key. The CLI supports browser login and API-key management. Hosted OAuth does not require exchanging a user-supplied API key.
For a local stdio client that uses an MCP configuration file:
{
"mcpServers": {
"userintuition": {
"command": "npx",
"args": ["-y", "@userintuition-ai/mcp"],
"env": {"USERINTUITION_API_KEY": "ui_sk_your_key_here"}
}
}
}Keep real keys out of version control. For shell workflows:
npm install -g @userintuition-ai/mcp
userintuition-mcp login
userintuition-mcp list
userintuition-mcp list_studiesStart with a read such as list_studies to check your connection. See the current MCP setup guide for client-specific instructions and the research skills for workflow guidance.
The six research tool groups
MCP exposes study planning, recruitment, interviews, results, evidence search, and supporting configuration operations. The CLI provides shell access to research workflows. Use the current tool catalog and API reference for exact names and arguments; tool counts vary by release.
| Group | Tools | What agents can do |
|---|---|---|
| Studies | 12 | Create and customize drafts, inspect and update metadata, launch or control fielding, delete a study, generate and retrieve its report |
| Participants | 5 | List, create, inspect and update participant records; send a requested reward |
| Interviews | 5 | List and inspect interviews, retrieve usage and participant-grouped records, delete an interview |
| Panel reference and feasibility | 4 | Discover country/language combinations; submit, list and retrieve feasibility requests |
| Webhooks | 2 | Create or delete completed-interview callbacks |
| Configuration catalogs | 5 | Discover languages, modes, study types, individual types and voices |
The study workflow connects the research brief to interviews, reports, and source references that the calling agent can inspect and reuse.
Agents can search findings and participant responses across authorized studies, then retrieve the underlying reports and interviews. Results preserve study context and source links; the calling agent interprets the evidence. Search coverage is explicit, and retrieving evidence does not launch research.
Design and approve the study
Create a metadata draft with create_study, then send the research brief through customize_study. Relay any planning questions to the user. Retrieve the persisted plan with get_study and obtain approval before recruitment. The user must choose panel or BYOP explicitly.
These are illustrative MCP tool calls in workflow order, not an unattended launch script. Replace placeholder IDs with values returned by the server. The example assumes the user has chosen panel recruitment.
create_study({"name":"Headline research","recruiting_method":"panel"})
customize_study({"study_id":"<study-id>","message":"Compare our three headline options with US product managers. Explore relevance, clarity, and reasons for preference. <include the options>"})Continue customize_study with the user’s answers if it returns a planning question. Once a plan is saved:
get_study({"study_id":"<study-id>"})Show the full saved plan for approval. Use Customize Plan for audience criteria, screeners, and concept or prototype assets; create_study is not a raw discussion-guide submission tool. Voice in English with Elliot is the default unless the user requests other supported settings. Prototype tests support voice or video, not chat.
Estimate and recruit
For a panel study, use launch_panel with dry_run: true to obtain the recruitment estimate. Show the country, language, cost, and timeline; launch with the same settings after approval. Each launch specifies one country. Audiences below 10% incidence require a feasibility request.
launch_panel({"study_id":"<study-id>","target":25,"incident_rate":50,"country_code":"US","dry_run":true})The target and incidence above are illustrative, not a claim about your audience. Use the approved values. A dry run estimates recruitment; it does not field interviews. After approval, call the same tool with the same settings and dry_run: false. Timing depends on the audience and fielding conditions.
For a BYOP study, use create_participants with 1–100 unique participant emails per batch after the saved plan and invitations are approved. Invitations send by default; set silent: true on individual participant records when invitations should not send. Source customer lists through your own authorized export or integration; MCP has no direct CRM segment-sync tools.
Monitor and retrieve the evidence
Interviews complete over time. Record the study ID so a later session can resume. Provisioning status describes interviewer setup; it does not by itself prove that a panel is fielding or complete.
list_interviews({"study_id":"<study-id>","status":"completed","page":1,"page_size":20})
get_study_report({"study_id":"<study-id>"})Paginate before counting completions or comparing quality. Study results expose findings, participant responses, sample profiles, recommendations, and source references in JSON. Use generate_report when analysis is needed, and get_interview to verify supporting messages and recording links. Preference shares, credibility scores, and ranked themes are not guaranteed typed fields in this response.
generate_report works on a selected study. If a write times out, inspect the saved study or report before repeating it. A timeout alone does not establish that the operation failed.
For automated notification, the current tools support account-wide completed-interview webhooks. New registrations provide a signing secret. Delivery has no automatic retries, so consumers should reconcile notifications against interview records.
Integration patterns
For a quick assumption check, narrow the brief to one decision and use the standard study flow. For a larger moderated study, save the study ID and return for interviews and a report as fieldwork progresses. Neither pattern requires a conversation to remain open throughout recruitment.
For custom agents, pass the MCP tool schemas through your framework’s supported MCP client. Keep approval state with the exact plan and recruitment estimate so a later action cannot silently use changed settings.
Testing locally
First verify discovery and a read such as list_studies. A panel dry run returns an estimate; it is not a sandbox for the entire workflow. Creating a participant record can send an invitation, and an actual panel launch starts recruitment. Use fixtures for unattended integration tests and run real research only with the study owner’s approval.
Authentication and error handling
Hosted connections use OAuth. Local stdio uses an API key supplied through the environment. Do not log credentials or include them in a repository.
Preserve the tool’s error response and treat it as a failed operation. For an uncertain write, read persisted state before retrying. Do not apply a blanket retry policy to study creation, invitations, rewards, or launch calls.
What to build first
Start with one decision: retrieve a prior study, or design and approve a small new study. Add polling or webhooks only when your integration needs unattended completion handling. Use research skills to give the agent the supported workflow without maintaining a second set of tool descriptions.