MCP Consumer Research Integration Guide for Developers

AI agents in 2026 can write code, review PRs, draft emails, and summarize meetings. What they cannot do on their own is ask 500 real consumers what they think. Training data answers that question with plausible text, not consumer evidence. For product teams shipping real features to real users, that gap matters.

The Model Context Protocol (MCP) closes it. MCP is the open standard, now backed by Anthropic, OpenAI, Google, and Microsoft, that lets AI agents discover and invoke external tools through a single interface. User Intuition’s MCP server exposes real consumer research as a tool call. Any MCP-capable agent — Claude Desktop, Claude Code, Cursor, ChatGPT, custom LangChain or CrewAI agents — can launch studies, retrieve structured results, and query accumulated intelligence without a custom API wrapper.

This guide is for developers integrating the MCP server into an AI workflow. It covers configuration for each supported client, the 9 capability groups, concrete invocation examples, integration patterns, error handling, and how to test locally.

Why MCP Instead of Direct REST API Calls?

Before MCP, integrating consumer research into an AI workflow meant writing a custom wrapper per client. A Cursor integration, a Claude Desktop integration, a ChatGPT plugin, a LangChain tool — each a separate codebase with its own auth, error handling, and schema.

MCP collapses those integrations into one. The server exposes a single tool catalog. Every MCP-capable client discovers those tools through the standard initialization handshake and invokes them through the standard tool-call schema. One integration works everywhere.

There’s a second benefit: schema awareness. When an agent calls ask_humans, the MCP client validates the arguments against the tool schema before the request leaves the client. That catches errors — missing fields, wrong types — locally instead of round-tripping to the server. For agents making tool calls at inference time, local validation is the difference between a recovered error and a burned turn.

For backend batch jobs that don’t need tool discovery or schema negotiation, direct REST calls against the User Intuition API are still a reasonable choice. For anything agent-driven, MCP is the right abstraction.

Prerequisites

Before you start:

1. A User Intuition account. Sign up at app.userintuition.ai/sign-up. The Starter plan gives you 3 free interviews to test the integration end-to-end.
2. An API key. Go to Settings → API Keys at app.userintuition.ai and generate a key. Keys start with ui_sk_. Store it in an environment variable — never commit it.
3. Node 20+. The package runs via npx — no local build or global install required.

How Do You Configure the MCP Server?

The server ships as userintuition-mcp on npm (current: v0.2.5). For stdio clients, zero install via npx -y @userintuition-ai/mcp. Auth is the USERINTUITION_API_KEY environment variable.

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. All 72 User Intuition tools appear in the tool tray automatically.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add userintuition -- npx -y @userintuition-ai/mcp

Then set USERINTUITION_API_KEY in your shell environment. For project-scoped config, Claude Code reads .mcp.json at the project root — same JSON shape as Claude Desktop.

VS Code

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {
        "USERINTUITION_API_KEY": "ui_sk_your_key_here"
      }
    }
  }
}

ChatGPT

ChatGPT connects via Streamable HTTP with OAuth. The MCP server at https://mcp.userintuition.ai/mcp auto-discovers the OAuth configuration, so ChatGPT handles the auth flow automatically.

Setup:

1. Settings → Apps & Connectors → Advanced → Enable Developer Mode
2. Settings → Connectors → Create:
   • Name: User Intuition
   • MCP Server URL: https://mcp.userintuition.ai/mcp
   • Authentication: OAuth (auto-discovered)

No API key needed for ChatGPT — the OAuth flow connects your User Intuition account directly.

The 9 Capability Groups

The server exposes 72 tools across 9 groups. Here is the structure; for the full per-tool reference see docs.userintuition.ai/mcp-server/overview.

The server also exposes 4 MCP prompts — moderator-guide templates (study_planning_context, chat_planning_context, concept_test_planning_context, concept_test_chat_planning_context) — that load the canonical study structure from the backend on demand. Use them before create_assistant to ensure the generated system_prompt matches what the in-app dashboard produces.

Invocation Example 1: Ask Real Humans a Question

ask_humans is the entry point for Human Signal studies. It supports three modes: preference (compare 2-5 options), claim (validate a belief), and message (test copy clarity).

{
  "tool": "ask_humans",
  "arguments": {
    "mode": "preference",
    "question": "Which pricing structure would you prefer for a product research tool?",
    "options": [
      "Pay per interview ($25/interview, no annual contract)",
      "Monthly subscription ($2,499/month, 100 interviews included)"
    ],
    "audience": {
      "role": "Product manager or UX researcher",
      "company_size": "50-500 employees"
    },
    "sample_size": 20
  }
}

The call returns a study ID and estimated completion time. Retrieve results later with get_results.

Invocation Example 2: Full Moderated Study Workflow

For in-depth interviews with open-ended probing, the workflow runs through the Research Platform group:

// Step 1: Create the study
{
  "tool": "create_assistant",
  "arguments": {
    "name": "Churn exit interviews — Q2 cohort",
    "study_type": "churn",
    "system_prompt": "You are conducting a 20-minute exit interview..."
  }
}

// Step 2: ALWAYS get_assistant before update_assistant
// screener_questions REPLACES the full list — read first or you lose existing screeners
{
  "tool": "get_assistant",
  "arguments": { "assistant_id": "asst_..." }
}

// Step 3: Update with screener questions (merging with what was returned above)
{
  "tool": "update_assistant",
  "arguments": {
    "assistant_id": "asst_...",
    "screener_questions": [ ... ]
  }
}

// Step 4: Invite participants from a Shopify or HubSpot segment
{
  "tool": "bulk_create_invites_from_segment",
  "arguments": {
    "assistant_id": "asst_...",
    "segment_id": "seg_..."
  }
}

// Step 5: After interviews complete, trigger analysis
{
  "tool": "analyze_transcripts",
  "arguments": { "assistant_id": "asst_..." }
}

The get_assistant before update_assistant step is mandatory — the package enforces this discipline in its system instructions because screener_questions replaces the full list, not appends to it.

Invocation Example 3: Query the Intelligence Hub

query_intelligence lets an agent ask a grounded question across all past studies in the Customer Intelligence Hub. Use it before launching new research to check whether the question has already been answered.

{
  "tool": "query_intelligence",
  "arguments": {
    "question": "What did enterprise admins say about SSO pricing in the last 90 days?",
    "session_id": "sess_..."
  }
}

If relevant findings exist, the agent can skip launching a new study. Every study feeds the Intelligence Hub automatically, so the system compounds over time.

Integration Patterns

For Fast Assumption Checks (Human Signal)

Human Signal studies with 10-20 participants typically complete in 2-3 hours. An agent can kick off the study with ask_humans and, if the session is long-lived (Claude Desktop chat sessions, for instance), poll for completion using get_results within the same session. Short studies fit inside a typical work session.

For Full Moderated Studies (Fire and Check Back)

Full moderated interview studies with 50+ participants run 24 hours. The pattern is fire-and-check-back:

1. Agent calls create_assistant and sets up invites — typically initiated by the user in a session
2. Agent confirms: “I’ve set up the study. I’ll retrieve findings when interviews are complete.”
3. User returns to a new session later and asks for results
4. Agent calls analyze_transcripts to trigger report generation, then get_assistant_report or query_intelligence to retrieve findings

There are no webhooks and no callback registration. The MCP server is stateless between sessions; the User Intuition backend holds the study state. The agent retrieves it on demand.

This is the same “fire and check back” pattern the app’s own dashboard uses — the difference is that an agent can retrieve and synthesize findings directly into a PRD, deck outline, or analysis without the user navigating the UI.

Custom Agents (LangChain, CrewAI)

Any framework that can manage a subprocess and speak MCP can connect. LangChain MCP adapters launch the npm CLI as a stdio process:

import subprocess
from langchain_mcp_adapters.client import MCPClient

process = subprocess.Popen(
    ["npx", "-y", "@userintuition-ai/mcp"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    env={**os.environ, "USERINTUITION_API_KEY": os.environ["USERINTUITION_API_KEY"]},
)
client = MCPClient.from_stdio(process)
tools = await client.get_tools()

CrewAI uses a similar pattern through its tools interface. The key difference from HTTP-based MCP clients: stdio requires managing the subprocess lifecycle. Start the process before the agent run and terminate it cleanly after.

Authentication

Stdio (Claude Desktop, Cursor, Claude Code, VS Code): set USERINTUITION_API_KEY in the env block of the client config. The key starts with ui_sk_ and is generated at Settings → API Keys in the app. A key carries the full access of the account that created it — there are no granular scopes.

HTTP (ChatGPT): OAuth, auto-discovered by ChatGPT from the server URL. No manual OAuth flow to implement; the Connectors UI handles it. Scopes and refresh tokens are managed by Clerk (the auth provider) internally.

There are no webhooks, no webhook secrets, and no callback registration surface.

Error Handling

Tool-call errors come back through standard MCP error responses. When the User Intuition backend rejects a request (invalid arguments, insufficient credits, a study that cannot be edited in its current state), the tool returns a structured error payload in the MCP content block — a text or JSON response with error details.

Patterns to handle:

• Credential errors: a missing or invalid USERINTUITION_API_KEY surfaces immediately on the first tool call. Regenerate at Settings → API Keys.
• Insufficient credits: the tool error will indicate payment is required. Add credits at Settings → Billing.
• State conflicts: update_assistant on a study that’s already launched, or edit_study on a Human Signal study that’s past the editable window, returns an error describing the constraint. Always get_assistant first to confirm the current state before writing.
• Transient errors: standard MCP retry with exponential backoff. The underlying REST API is the same one that powers the app dashboard.

The MCP Inspector (see below) is the fastest way to inspect raw request/response payloads during development.

Testing Locally

Two tips that save real time:

Use dry_run: true on ask_humans. Pass dry_run: true in the ask_humans arguments to get a cost estimate and audience feasibility check without launching the study or consuming credits. Use this to verify your audience targeting and sample size are viable before committing.

Use the MCP Inspector. The MCP Inspector lets you browse all 72 tools and test them interactively against a live server:

USERINTUITION_API_KEY=ui_sk_your_key_here npx @modelcontextprotocol/inspector npx -y @userintuition-ai/mcp

This starts the stdio server and opens an interactive UI where you can browse tool schemas, construct tool calls, and inspect raw responses — without going through Claude Desktop or Cursor. It’s the fastest way to verify your key is working and to understand a tool’s expected arguments before wiring it into an agent.

What to Build First

The fastest path to a working integration:

1. Configure Claude Desktop with the stdio config above (30 seconds)
2. Open a new chat and ask: “Use User Intuition to check whether 20 SMB product managers would prefer pay-per-interview or monthly subscription pricing”
3. Watch Claude call ask_humans with mode preference, then retrieve results with get_results when the study completes
4. Extend to Cursor, Claude Code, or a custom LangChain agent using the same config pattern

Most developers have a working integration in under an hour. The full technical reference — all 72 tools with arguments and response schemas — lives at docs.userintuition.ai/mcp-server/overview.

The npm package (@userintuition-ai/mcp, invoked via npx -y @userintuition-ai/mcp) is on version 0.2.5. For the product surface this MCP server connects to, see our agentic research platform. For a non-technical overview of what this enables, see how to connect AI agents to consumer research via MCP.

Ready to ship? Generate an API key at Settings → API Keys in app.userintuition.ai and start building.