Usercall

Usercall MCP - AI agents that run real user interviews

AI can build products. But it still doesn't talk to users.

Give your AI agents the ability to ask real users why.

Usercall MCP runs AI-moderated voice or text interviews with real users. Use it to learn why users churn, where onboarding drops off, or why an action failed, and get themes, insights, and verbatim quotes.

Why this exists

AI agents can now build and ship products extremely quickly.

But most agents still rely on synthetic feedback or assumptions about users.

Usercall MCP lets agents gather real qualitative feedback directly from users.

---

Choose a connection

Recommended: hosted MCP (Claude, ChatGPT, Cursor, Grok Bot)

Add `https://mcp.usercall.co` as a remote MCP connector / custom connector.

• OAuth sign-in (no API key, no npx)
• Same tools as this package (studies + Research Triggers)
• Docs: app.usercall.co/docs/mcp
• Cursor Directory / Grok Bot: this repo ships .mcp.json so cursor.directory can install the hosted connector. Grok Bot cannot run the local npx package.

ChatGPT plugin package

Root plugin.json, mcp.json, and skills/ are the ChatGPT submission package (version in plugin.json, not package.json). Validate it and write the ZIP with:

pnpm plugin:check

The ZIP is dist/usercall-chatgpt-plugin- .zip. Do not upload it unless someone asks to submit.

Install in Cursor

Community. Already listed at cursor.directory/plugins/usercall.

Official Marketplace. Once the listing is live, install from the Cursor Marketplace. Submit the repo at cursor.com/marketplace/publish.

Manual. Add the hosted MCP. OAuth sign-in, no API key.

{

"mcpServers": { "usercall": { "url": "https://mcp.usercall.co" } } }

This package: local / API-key / machine-to-machine

Use @usercall/mcp over stdio when you want a Bearer API key (scripts, local clients, M2M).

1. Sign in at app.usercall.co → Home → Developer → Create API key
2. Run npx -y @usercall/mcp with USERCALL_API_KEY

---

Example workflow

Agent: "Why are users confused about onboarding?"

→ create_study → share interview_link with users → get_study_results

The returned interview_link is an https://app.usercall.co/interview/ URL. Share it with participants through email, Slack, Discord, or in-product prompts.

Example result:

{

"themes": [ { "name": "Onboarding confusion", "summary": "Users struggled to understand the second step.", "quotes": [ "I wasn't sure what the app was asking me to do.", "I didn't know I had to verify my email before continuing." ] }, { "name": "Pricing confusion", "summary": "Free plan limits were not clearly communicated.", "quotes": ["I wasn't sure if the free plan included analytics."] } ] }

How it works

AI Agent

↓

Usercall MCP (hosted OAuth or this stdio package)

↓

Usercall Agent API

↓

Real user interviews

↓

Themes and verbatim quotes returned to the agent

With Research Triggers, the agent can also target users in your product:

Analytics MCP (PostHog, Mixpanel, …) finds a behavior

↓

Usercall MCP creates a study and a paused Research Trigger

↓

You activate it in Usercall

↓

The Usercall SDK invites matching users to an interview right after the behavior

---

Research Triggers

Analytics tells an agent *what* users do. Research Triggers let it ask them *why*.

User:  "Look at our PostHog data and find something worth investigating."

Agent (PostHog MCP): users who test a study rarely launch one.

Agent (Usercall MCP): list_trigger_events() → study_tested, study_launched, … get_trigger_event_schema("study_tested") → properties: source, interview_type traits: plan ("free", "pro"), account_type create_study(...) or list_studies() create_research_trigger({ study_id, event_name: "study_tested", traits: { plan: "free" }, sampling_percent: 25, max_invites_per_day: 10 }) → status: "paused", summary, activation_url

Agent: "I've prepared a Research Trigger. When: study_tested · Audience: plan = free · 25% sampled · max 10 invites/day. It's paused. A human activates it here: "

• The Usercall SDK has to be installed. If list_trigger_events returns nothing, call get_trigger_sdk_setup (with your analytics provider and event names) to get the snippet. Coding agents can install it for you.
• Only events Usercall has actually received can be used. Filters are exact matches on event properties or user traits. get_trigger_event_schema shows which field is which.
• Unsupported conditions are rejected, not silently dropped. These include event counts, sequences, absence ("did not do X"), time windows, and not-equals. get_trigger_capabilities returns the full list.

---

Local install (API key)

1. Get an API key

Sign in at app.usercall.co → Home → Developer → Create API key

2. Add to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "usercall": { "command": "npx", "args": ["-y", "@usercall/mcp"], "env": { "USERCALL_API_KEY": "your_key_here" } } } }

Cursor (.cursor/mcp.json):

{

"mcpServers": { "usercall": { "command": "npx", "args": ["-y", "@usercall/mcp"], "env": { "USERCALL_API_KEY": "your_key_here" } } } }

For Claude, ChatGPT, or Cursor remote connectors, prefer https://mcp.usercall.co instead of this JSON config.

Restart your MCP client.

3. Ask your agent

Run user interviews to understand why users drop off during onboarding.

Context:

• B2B SaaS product
• 3-step signup flow

Goal: Identify confusion points and friction.

Target interviews: 5 Language: ko Interview mode: voice

Show participants this prototype during the interview: https://www.figma.com/proto/abcd1234/onboarding-flow

The agent will:

1. create a study
2. return an interview link
3. collect responses
4. return the summary (themes, insights, and risks)

---

Structured tool example

Equivalent create_study tool call:

create_study

key_research_goal: "Understand why users drop off during onboarding" business_context: "B2B SaaS signup flow" target_interviews: 5 languages: ["en"] interview_mode: "voice"

study_media: type: "prototype" url: "https://www.figma.com/proto/abcd1234/onboarding-flow" description: "New onboarding flow concept"

---

Tools

create_study

Create an AI-moderated interview study to learn why users churn, drop off in onboarding, fail an action, or where a product assumption is wrong. Returns HTTP 201 with study_id and interview_link for a voice, text, or voice-and-text interview. interview_link is an https://app.usercall.co/interview/ URL. key_research_goal is required and cannot be changed later. business_context is optional. Defaults: target_interviews 1, duration_minutes 12, interview_mode voice. One active agent study per account. Does not run the interview or invite a participant. HTTP 402 includes checkout_url.

One locale turns the language picker off; two or more turn it on. Research goal cannot be changed after create.

study_media (optional). Visual stimulus shown during all interview questions:

• image: Direct image URL (.png, .jpg, .gif, .webp)
• prototype: Figma prototype URL (converted to interactive embed)
• Media is only visible to web participants; phone callers won't see it

update_study

Update an interview study: slots, guide questions, intro, languages, voice, or an image or Figma prototype shown to participants. Returns the updated study. key_research_goal cannot be changed. is_link_disabled true stops new interviews and keeps recordings. One locale hides the language picker; two or more show it. Query parameters on interview_link are ignored until enable_link_context is true. study_media null clears media. API errors include http_status. Does not dry-run the guide or invite a participant.

Pass study_media: null to clear media. The study_media object follows the same schema as in create_study.

get_study_status

Check whether interviews about churn, onboarding, or a failed action have started. Returns completed_interviews, target_interviews, interview_link, and next_step. interview_link is an `