When a qualitative research platform ships both an MCP server and a REST API, the natural question is which one to use. The answer depends on who makes the next decision: an AI agent at runtime, or your code at build time.
This guide is the decision framework. It covers what each interface exposes, how authentication, long-running work and event delivery differ, which workloads suit each, and how teams run both against the same studies. Both interfaces are fully supported, so the right choice depends on your workflow architecture, not on which protocol is newer. For teams building agent-native research workflows, the User Intuition research API and MCP server for AI agents supports both paths.
When should you use MCP, and when REST?
Use MCP when an AI agent decides the next step, and REST when your code already knows it. MCP fits conversational research: a person asks a question in Claude, ChatGPT or an IDE, and the agent discovers the research tools, plans the study, waits for approval and reads the findings back in the same thread. REST fits software: a scheduled pulse study, a study triggered by a product event, or a nightly export of transcripts to a warehouse. The two interfaces differ in four practical ways. MCP signs people in with OAuth, while REST sends an API key. An agent checks progress when someone asks, while a service polls job endpoints or listens for signed webhooks. An agent learns the operations from the tool list on connect, while a developer codes against the OpenAPI document. And because both reach the same studies and the same research library, many teams end up running both side by side.
What does each protocol expose?
MCP: tools an agent discovers at runtime
The Model Context Protocol exposes a research platform as typed tools that an AI agent discovers when it connects. Each tool’s name, description and input schema arrive with the connection, so the developer does not decide in advance which operations the agent will use.
The agent picks tools by context: for example, create_study to start a study and customize_study to send the brief through the planning step. The MCP research API reference maps every tool group and follows one study through them. The hosted server runs over Streamable HTTP at https://mcp.userintuition.ai/mcp, and a local stdio package serves clients that start a process of their own.
REST API: endpoints your code calls
The REST API exposes the same capabilities as named HTTP endpoints at https://api.userintuition.ai. A developer calls a specific endpoint, builds the request body from the documentation, and handles the JSON response in application code. The planning step, for example, is POST /api/public/v1/studies/{study_id}/customize-plan.
REST is a deterministic contract: the developer decides exactly which operation runs and when. That suits predictable, repeatable workflows. REST has its own machine-readable description too, in the OpenAPI document, which code generators and typed clients can read.
How do MCP and REST compare at a glance?
| Factor | MCP | REST |
|---|---|---|
| Who decides the next step | The agent, from context | Your code, at build time |
| How operations are learned | Tool list on connect | API reference and OpenAPI document |
| Sign-in | OAuth for people; organization API key for headless clients | API key as a bearer token |
| Long-running work | The agent checks progress on request, in any later session | Job endpoints to poll, or webhooks |
| Event delivery | Webhooks registered with a tool | Webhooks registered with an endpoint |
| Approval before spend | One click in Claude; confirm in the conversation elsewhere | Launch against a saved estimate |
| Retries | Idempotency keys on launch and other write tools | Idempotency-Key header on create and launch requests |
| Best for | Conversational research in Claude, ChatGPT or an IDE | Scheduled jobs, exports, product-event triggers |
Which factors decide between MCP and REST?
1. Agent involvement
MCP is the right choice when an AI agent drives the research workflow: deciding which study to run, which participants to target, when to retrieve results, and what to do with them. Tool discovery lets the agent make those decisions with full schema awareness.
REST is the right choice when a software service drives it. A backend job that runs the same study type every month does not need schema discovery; it already knows what to call.
2. Schema discovery
MCP provides tool schemas at connection time, so the agent needs no prior knowledge of the API. That matters for agent frameworks that route operations across many tools without developer-written routing.
REST asks the developer to read the reference and build explicit requests. When a new endpoint or field arrives, the developer updates the code, and typed clients generated from the OpenAPI document make that update quick.
3. Reach across clients
MCP lets one research server serve many agent clients with no per-client code: Claude, Claude Code, ChatGPT, Codex, Cursor, and any MCP-compatible framework. Each new MCP-capable tool reaches the same server without rework.
REST needs integration code, authentication handling and response parsing in each application that uses it, and in return stays the stable contract for backend work.
4. Error handling and retries
REST gives you direct control: HTTP status codes, retry logic in your application, and explicit error branches. An Idempotency-Key header on create and launch requests makes retries safe. For production batch jobs where reliability comes first, that transparency is an advantage.
MCP hands error handling to the agent framework and the client. That works well for interactive workflows and most cloud deployments, and the same idempotency keys protect agent retries, so a timed-out launch retried with the same key never fields a study twice.
How does authentication differ?
The two interfaces assume different callers, and their sign-in reflects it.
- Hosted MCP signs in with OAuth. A person connecting Claude, ChatGPT, Claude Code or Codex signs in once in the browser, and the client keeps the session. There is no key to copy, store or rotate. Each hosted URL, including the smaller tool profiles, is authorized on its own.
- Headless MCP clients use an organization API key. A cloud service that runs an agent without a person at the keyboard can send a key to the same hosted endpoint, and the local stdio package reads one from
USERINTUITION_API_KEY. - REST sends an API key as a bearer token. Keys begin with
ui_sk_and are created under Settings, then API Keys. Keep them in a secret manager or environment variable rather than in code. - The CLI signs in through the browser with
userintuition-mcp login, which suits a developer’s machine and scripted reads.
Every request on every interface is scoped to your account, so an agent and a backend service see the same studies. A sensible split for a team that runs both is an OAuth sign-in for each researcher and one key for each backend service.
How do latency and long-running work differ?
The interface barely changes how long research takes, because fielding dominates: most panel studies fill within 24 hours, and the estimate shows the expected timeline for your audience and country before you approve. What differs is how the caller waits.
- Over MCP, each call returns quickly and the agent checks back when you ask. Planning turns can be queued with
queue_customize_studyand read withget_customize_study_job, report generation returns a job to check, and clients that support MCP Tasks run these as native tasks. Because every call hangs off the study ID, the agent can pick up the same study in tomorrow’s conversation. - Over REST, long operations are explicit jobs.
POST /api/public/v1/studies/{study_id}/customize-plan/jobsqueues a planning turn and returns a durable job ID,POST /api/public/v1/studies/{study_id}/reportqueues analysis and returns a job, and interview and slide exports run as jobs too. Your code polls the job endpoint or waits for a webhook. - On both, fielding progress returns completions against the target, quality counts and, once enough interviews are in, an expected finish.
The practical rule: in conversation, let the agent check in when a person asks; in code, never block a request thread on a study. Queue the work, return, and react to the event.
Should you use webhooks or polling?
Polling suits an agent in a conversation, and webhooks suit software that should react on its own.
- Polling.
get_fielding_progressover MCP, orGET /api/public/v1/studies/{study_id}/fielding-progressover REST, returns current progress whenever you ask. It needs no public endpoint, which is why it fits a chat agent that checks when someone asks how the study is going. - Webhooks. Signed HTTPS deliveries for
interview.completed,study.completedandreport.ready, plus participant events (screened, started, quality scored) and study lifecycle events (paused, resumed, stopped, quota reached). A webhook can cover one study or every study in the account. Register it with thecreate_webhooktool orPOST /api/public/v1/webhooks/; either way the signing secret appears once, at creation. You can send a signed test event that carries no participant or study data, list recent delivery attempts, and rotate the secret.
Choose webhooks when a service should act on an event, such as pulling the report into a dashboard when report.ready fires or alerting a team channel as interviews complete. Choose polling when a person is in the loop and asks for status. A robust integration uses both: the webhook wakes the service, and the service reads current state before acting. The developer integration guide shows signature verification in code.
How do MCP and REST compare in four workflow scenarios?
Scenario 1: Chat-driven research
A brand team asks an agent why shoppers are switching away from its sparkling water. The agent discovers the study tools, collects the brief, relays the planning questions, and comes back with the saved plan for approval.
Verdict: MCP. Each step depends on the last answer, and a person is in the conversation.
Scenario 2: Backend batch workflow
A scheduled job runs a monthly pulse study with the same five questions and the same audience, and exports the prior month’s transcripts to a data warehouse as CSV or JSONL. A panel launch can itself carry a weekly, monthly or quarterly frequency, so the recurring study is configured once.
Verdict: REST. The workflow is fixed and predictable, the retry logic lives in the application, and there is no need for discovery.
Scenario 3: Studies triggered by product events
When a subscriber downgrades, a webhook from your product triggers a study to understand the driver. The trigger is a product event; the workflow is mostly fixed, but the participant profile varies with the downgrade context.
Verdict: Either, or hybrid. REST works if the study parameters are deterministic. MCP works if an agent should shape the study from the context. Many teams start with REST for the main path and add MCP as the workflow grows more context-dependent.
Scenario 4: Questions about earlier research
Mid-conversation, an agent can ask questions across past research and get an answer cited to the interviews behind it.
Verdict: MCP. The question arises in the middle of a conversation, which is MCP’s strongest fit.
How do you migrate between MCP and REST, or mix them?
MCP → REST (narrowing down)
Teams often start with MCP for exploration, then lock specific operations into REST calls for production. Identify the tool calls in your MCP workflow that always run the same way, read the equivalent endpoint in the API reference, and rewrite those steps as HTTP calls. The rest of the MCP workflow keeps working alongside them.
REST → MCP (expanding capability)
Teams with existing REST integrations add MCP when they introduce an agent that needs dynamic tool selection. Add the MCP server to your agent framework, confirm the tools load, and move the agent-facing steps to MCP. Batch jobs that already work on REST stay as they are.
Hybrid (permanent architecture)
The most mature pattern treats REST and MCP as complementary. Interactive, context-driven research runs through MCP; scheduled, deterministic operations run on REST. One hybrid looks like this: a researcher briefs and approves a study from Claude over MCP, while a backend service holds a webhook for interview.completed and report.ready. When the report is ready, the service reads it over REST and writes the findings to the team’s warehouse, and a nightly job exports the transcripts as JSONL. The study ID ties the two halves together, so neither side needs to know how the other started the study.
How does User Intuition handle both protocols?
Both reach the same moderator and the same evidence. User Intuition’s AI moderator runs 20–30 minute interviews that ladder 5–7 levels deep, with a vetted 4M+ consumer panel (B2B audiences recruited to order per study), or your own participants. The agent shows you the saved plan and a cost estimate before anything is spent; in Claude you approve with one click, elsewhere you confirm in the conversation, and over REST your code launches against a saved estimate.
Every panelist call is reviewed by the User Intuition team, panelists pass a video identity check, and only interviews that pass quality scoring are billed; see how quality works. Voice interviews cost $30 each, and signup includes 3 free interviews with your own participants; panel recruiting is billed separately.
To see what either interface returns, explore an example study. Connect it in Claude, ChatGPT, Codex or Cursor in a few minutes (setup).
Which should you start with?
If you are building an AI agent that drives research decisions: start with MCP. Tool discovery is what makes the agent-driven pattern work.
If you are building a backend service that runs fixed research operations on a schedule: start with REST. A simpler contract and direct error handling suit it.
If you are not sure: start with MCP and note which tool calls always run in the same sequence. Move those to REST when the workflow settles. The MCP server docs and the API reference have what you need for the first integration.