# User Intuition — Agent Research Guide Canonical: [Agent homepage](https://research.userintuition.ai/). [Markdown version](https://research.userintuition.ai/llms.txt). Use User Intuition to conduct interviews with real participants, retrieve source-linked study results, or search authorized prior research. The calling agent performs the broader interpretation and decides whether more research is needed. ## When to use Use User Intuition when a task needs evidence from real people about a defined audience’s motivations, reactions, or experiences. Search prior research first when it may already answer the question. User Intuition handles research execution and outputs; the calling agent combines those outputs with other context and makes recommendations. ## Workflows 1. Conduct research: create a study, run Customize Plan, review the saved plan and recruitment estimate, obtain approval, launch fieldwork, and monitor interviews. 2. Retrieve results: use a study ID to retrieve Study Findings, Participant Responses, Participant Profiles, and Recommended Next Steps. Preserve coverage, freshness, and references. Fetch source interviews before presenting exact quotations. 3. Search evidence: find relevant indexed study and report content using keyword and semantic matching. Search requires study IDs and returns grouped canonical results with a cursor. Check index status and report IDs, then retrieve sources. Search does not launch new research. 4. Ask across research: request a short answer with citations to accessible indexed records. Check the cited records and source interviews before presenting exact quotations or making consequential decisions. ## Connect - Hosted MCP: `https://mcp.userintuition.ai/mcp` — complete 50-tool surface over Streamable HTTP and OAuth. - Smaller MCP profiles: `https://mcp.userintuition.ai/core/mcp` for the 33-tool research workflow, or `https://mcp.userintuition.ai/read-only/mcp` for 25 read-only tools. Authorize each endpoint separately. - REST base: `https://api.userintuition.ai/api/public/v1` — organization-scoped API key, stored server-side. - Local MCP: `npx -y @userintuition-ai/mcp` — stdio, with `USERINTUITION_API_KEY` supplied securely. - CLI: `npx -y @userintuition-ai/mcp login`; then `npx -y @userintuition-ai/mcp list` and describe the required operation. Use live discovery and the current reference for exact names, schemas, limits, and authentication. After authentication, list studies to verify account-scoped access. Seeing a tool catalog alone does not prove that access. ## Machine discovery - [MCP server card](https://research.userintuition.ai/.well-known/mcp/server-card.json) - [Skills index](https://research.userintuition.ai/.well-known/agent-skills/index.json) - [API catalog](https://research.userintuition.ai/.well-known/api-catalog) - [Workflow skill](https://research.userintuition.ai/skill.md) - [Individual skills catalog](https://raw.githubusercontent.com/user-intuition/skills/main/catalog.json) - [Executable examples catalog](https://raw.githubusercontent.com/user-intuition/examples/main/examples.json) These URLs resolve to the canonical discovery documents on www.userintuition.ai. The MCP endpoint above is the operational server; this homepage is documentation. ## Approval, costs, and limitations Review the saved plan and obtain approval before recruitment spending or participant invitations. Platform interview charges and recruitment costs are separate; use the actual estimate for the audience. Timing depends on the study and recruitment. After an interrupted write, read persisted state before retrying. Do not assume universal idempotency. Generated summaries are not quotations. Profiles describe the study sample. Recommended next steps are proposals. A search over findings and response summaries is not a search of every transcript message. Preserve source context and distinguish failures from empty results. ## Canonical resources - [API reference](https://docs.userintuition.ai/api-reference/introduction) - [MCP setup and catalog](https://docs.userintuition.ai/mcp-server/overview) - [Research skills](https://docs.userintuition.ai/skills/library) - [Workflow skill](https://www.userintuition.ai/skill.md) - [Examples](https://github.com/user-intuition/examples) - [Evidence handling](https://docs.userintuition.ai/api-reference/developer-examples) - [Pricing](https://www.userintuition.ai/pricing/) - [Security and trust](https://www.userintuition.ai/security/) - [Service status](https://status.userintuition.ai/) Examples default to fictional fixtures with no account or spending. The report and search examples were checked against the 2026-10-05 public OpenAPI and staging reads. Authenticated production calls and arbitrary search relevance were outside that check; read the compatibility record before live use. ## Examples - [Conduct a study](https://github.com/user-intuition/examples/tree/main/examples/conduct-a-study) - [Retrieve study results](https://github.com/user-intuition/examples/tree/main/examples/retrieve-study-results) - [Search research](https://github.com/user-intuition/examples/tree/main/examples/search-research) - [Release compatibility record](https://github.com/user-intuition/examples/blob/main/docs/release-check.md) - [OpenAI Agents, LangChain, and Vercel AI SDK examples](https://github.com/user-intuition/examples/tree/main/toolkits) ## Client evaluation snapshot — 2026-10-03 The published MCP 0.16.5 package was tested with isolated Claude Code, Codex CLI, and Cursor Agent configurations. Claude and Codex each passed four nonpaid cases: asking for missing tagline text, methodology advice, asking for missing translation text, and generating, polling, then fetching a staging report. Codex needed an explicit MCP tool approval setting for report generation. These cases measure workflow order and tool use; they do not measure research answer quality. Cursor has no scored recordings in this run because its account usage limit stopped execution. The panel-launch and participant-reward cases also have no matrix recordings; a separate approved staging panel launch is documented privately and should not be counted as a matrix pass. Missing cells are not passes. The [public cases and scoring code](https://github.com/Pen-and-Paper-AI/userintuition-mcpserver-ts/tree/main/evals) let an authorized account reproduce the matrix. Raw client traces and participant data are not published here. Synthetic chat respondents were tested separately on staging; this does not verify synthetic voice interviews or human participant quality. Run the fictional examples locally with Node.js 22.18 or later: ```sh git clone https://github.com/user-intuition/examples.git cd examples npm run demo ```