Usercall MCP

Usercall MCP - 能开展真实用户访谈的 AI Agent

AI 可以构建产品，但仍然不会和用户交流。

让你的 AI Agent 能够询问真实用户背后的原因。

Usercall MCP 可与真实用户开展由 AI 主持的语音或文字访谈。用它了解用户为何流失、引导流程在哪一步出现用户流失，或某项操作为何失败，并获取主题、洞察和原话引述。

为什么要用它

AI Agent 现在可以极快地构建和发布产品。

但大多数 Agent 仍然依赖模拟反馈或对用户的臆测。

Usercall MCP 让 Agent 能够直接从用户那里收集真实的定性反馈。

---

选择连接方式

推荐：托管 MCP（Claude、ChatGPT、Cursor、Grok Bot）

添加 https://mcp.usercall.co 作为远程 MCP 连接器／自定义连接器。

• 通过 OAuth 登录（无需 API 密钥，无需 npx）
• 与此软件包提供相同的工具（研究 + Research Triggers）
• 文档：app.usercall.co/docs/mcp
• Cursor Directory / Grok Bot：此仓库提供 .mcp.json，因此 cursor.directory 可以安装托管连接器。Grok Bot 无法运行本地 npx 软件包。

ChatGPT 插件包

根目录下的 plugin.json、mcp.json 和 skills/ 是 ChatGPT 提交包（版本号在 plugin.json 中，而非 package.json）。验证并生成 ZIP 文件：

pnpm plugin:check

ZIP 文件为 dist/usercall-chatgpt-plugin-<version>.zip。除非有人要求提交，否则不要上传。

在 Cursor 中安装

社区版。 已列入 cursor.directory/plugins/usercall。

官方市场。 上架后，可从 Cursor Marketplace 安装。在 cursor.com/marketplace/publish 提交仓库。

手动安装。 添加托管 MCP。通过 OAuth 登录，无需 API 密钥。

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

此软件包：本地／API 密钥／机器对机器

需要使用 Bearer API 密钥时（脚本、本地客户端、M2M），通过 stdio 使用 @usercall/mcp。

1. 在 app.usercall.co 登录 → 主页 → 开发者 → 创建 API 密钥
2. 设置 USERCALL_API_KEY 后运行 npx -y @usercall/mcp

---

示例工作流

Agent: "Why are users confused about onboarding?"

→ create_study
→ share interview_link with users
→ get_study_results

返回的 interview_link 是一个 https://app.usercall.co/interview/ URL。通过电子邮件、Slack、Discord 或产品内提示词将其分享给参与者。

示例结果：

{
  "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."]
    }
  ]
}

工作原理

AI Agent

↓

Usercall MCP（托管 OAuth 或此 stdio 软件包）

↓

Usercall Agent API

↓

真实用户访谈

↓

向 Agent 返回主题和原话引述

借助 Research Triggers，Agent 还可以在你的产品中定位用户：

Analytics MCP（PostHog、Mixpanel，……）发现某种行为

↓

Usercall MCP 创建一项研究和一个已暂停的 Research Trigger

↓

你在 Usercall 中将其激活

↓

Usercall SDK 会在用户出现相应行为后，立即邀请符合条件的用户参加访谈

---

Research Triggers

分析会告诉 Agent 用户做了什么。Research Triggers 让它能询问用户为什么。

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: <activation_url>"

• 必须安装 Usercall SDK。 如果 list_trigger_events 没有返回任何内容，请调用 get_trigger_sdk_setup（提供你的分析服务商和事件名称）获取代码片段。编码 Agent 可以替你安装。
• 只能使用 Usercall 实际收到的事件。 筛选条件会与事件属性或用户特征进行精确匹配。get_trigger_event_schema 会显示各字段的类型。
• 不支持的条件会被拒绝，而不会被静默丢弃。 包括事件次数、事件序列、事件缺失（“未执行某操作”）、时间范围和不等于。get_trigger_capabilities 会返回完整列表。

---

本地安装（API 密钥）

1. 获取 API 密钥

在 app.usercall.co 登录 → 主页 → 开发者 → 创建 API 密钥

2. 添加到 MCP 客户端

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"
      }
    }
  }
}

对于 Claude、ChatGPT 或 Cursor 远程连接器，建议使用 https://mcp.usercall.co，而不是此 JSON 配置。

重启 MCP 客户端。

3. 向 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

Agent 将会：

1. 创建一项研究
2. 返回访谈链接
3. 收集回复
4. 返回摘要（主题、洞察和风险）

---

结构化工具示例

等效的 create_study 工具调用：

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"

---

工具

create_study

创建一项由 AI 主持的访谈研究，了解用户流失、在引导流程中途退出、未能完成某项操作的原因，或产品假设不成立的地方。对于语音、文本或语音与文本访谈，返回 HTTP 201，并附带 study_id 和 interview_link。interview_link 是一个 https://app.usercall.co/interview/ URL。必须提供 key_research_goal，且之后无法更改。business_context 为可选项。默认值：target_interviews 为 1，duration_minutes 为 12，interview_mode 为语音。每个账户只能有一项进行中的 Agent 研究。不会运行访谈或邀请参与者。HTTP 402 响应中包含 checkout_url。

字段	类型	必填	默认值
key_research_goal	字符串（5–2000）	是
business_context	字符串（5–2000）	否
additional_context_prompt	字符串	否
target_interviews	数字（1–200）	否	1
languages	字符串[]	否
duration_minutes	数字（5–65）	否	12
interview_mode	voice | text | voice_and_text	否	voice
voice_gender	female | male	否
enable_link_context	布尔值	否
custom_link_variables	{ key, label?, default_value? }[]	否
metadata	对象	否
study_media	对象	否

设置一种语言会关闭语言选择器；设置两种或更多语言会开启语言选择器。创建后无法更改研究目标。

study_media（可选）。在所有访谈问题中展示的视觉材料：

字段	类型	必填
type	image | prototype	是
url	字符串（URL）	是
description	字符串（最多 500 个字符）	否

• image：直接图片 URL（.png、.jpg、.gif、.webp）
• prototype：Figma 原型 URL（将转换为交互式嵌入内容）
• 媒体仅对网页参与者可见；电话参与者无法看到

update_study

更新访谈研究：时段、访谈指南问题、开场白、语言、语音，或向参与者展示的图片或 Figma 原型。返回更新后的研究。无法更改 key_research_goal。将 is_link_disabled 设为 true 会停止新的访谈并保留录音。只有一种语言时会隐藏语言选择器；有两种或更多语言时会显示。除非 enable_link_context 为 true，否则 interview_link 上的查询参数会被忽略。将 study_media 设为 null 会清除媒体。API 错误包含 http_status。不会试运行访谈指南，也不会邀请参与者。

字段	类型	必填
study_id	uuid 字符串	是
target_interviews	数字（1–200）	否
is_link_disabled	布尔值	否
ai_agent_intro_message	字符串	否
key_learning_goals	字符串	否
workflow_end_message	字符串	否
workflow_questions	{ text, ... }[]	否
interview_mode	voice | text | voice_and_text	否
languages	字符串[]	否
voice_gender	female | male	否
enable_link_context	布尔值	否
custom_link_variables	{ key, label?, default_value? }[]	否
study_media	对象或 null	否

传入 study_media: null 可清除媒体。study_media 对象遵循与 create_study 相同的架构。

get_study_status

检查有关客户流失、入门引导或操作失败的访谈是否已开始。返回 completed_interviews、target_interviews、interview_link 和 next_step。interview_link 是一个 https://app.usercall.co/interview/ URL。访谈数为 0 时，状态为 status: "not_started"。running 表示访谈正在进行。running 和 analyzing 状态不包含调查结果、主题或引述。如果已准备好的审核仍有尚未应用的编辑，next_step 为 update_study。指南与这些编辑一致后，或没有编辑时，如果存在终态模拟或审核且已完成的访谈仍为 0，则正确的下一步是 share。不会更改研究。

字段	类型
study_id	uuid 字符串

状态值：not_started · running · analyzing · complete

get_study_results

获取真实用户参与访谈后的调查结果：主题、洞见、风险和逐字引述。省略 format 或将其设为 summary 时，返回主题、洞见和风险。format=full 还会返回转录内容。主题为空表示分析尚未就绪。不会创建访谈或编辑指南。

字段	类型	必填
study_id	uuid 字符串	是
format	summary | full	否

摘要和完整响应都包含研究进度字段和分析输出。

simulate_interview

在真实参与者加入前，对访谈指南进行试运行，其中包括有关流失、引导流程或操作失败的问题。启动时省略 simulation_id；操作会立即返回 status: "running" 和一个 simulation_id。传入 simulation_id 可读取该次运行结果。省略 persona 时，服务端会根据研究问题编写一个角色设定，其中会说明此人没有做过研究所探讨的事。传入的角色设定会原样使用：name 长度为 1–80 个字符，prompt 长度为 1–4000 个字符。结果状态为 pass、fail 或 error。完成后的对话记录格式为 [{ "role": "agent" | "user", "content": "..." }]。不要期待返回 call_id、时区或时间戳。每个账户每天最多进行 5 次模拟（按 UTC 计算）。HTTP 429 表示已达到每日上限。试运行不会更改 completed_interviews，也不会邀请参与者。

字段	类型	必填
study_id	uuid 字符串	是
simulation_id	uuid 字符串	否
persona	{ name, prompt }	否
persona.name	字符串（1–80 个字符）	传入 persona 时
persona.prompt	字符串（1–4000 个字符）	传入 persona 时

省略 simulation_id，以 POST /api/v1/agent/studies/{studyId}/simulations 发起模拟。传入 simulation_id，以 GET 获取该次模拟。此工具不会轮询。启动时省略 persona，服务端会编写一个角色设定。传入的 persona 会原样转发。

review_study

在真实用户看到问题前，审查访谈指南，其中包括有关流失、引导流程或操作失败的问题。响应正文保留 findings，并新增 suggested_edits。suggested_edits 是一个 update_study 请求正文；如果无需修改，则为 null。将 suggested_edits 原样发送给 update_study。不会为你应用任何修改。消耗 1 个额度。请求仅包含 study_id；不接受 call_ids。即使应用内的审查控件被隐藏，此功能仍可使用。HTTP 402 响应中包含 checkout_url。只读取指南：不读取对话记录。

字段	类型	必填
study_id	uuid 字符串	是

仅发送 study_id。不会发送 call_ids。非 null 的 suggested_edits 值就是 update_study 请求正文，保持不变。

delete_study

永久删除访谈研究、其录音和未使用的预留额度。此操作无法撤销。不会删除产品内的研究触发器。

字段	类型	必填
study_id	uuid 字符串	是

研究触发器工具

工具	用途
get_trigger_capabilities	支持哪些产品内触发条件。单个事件、精确属性或特征、URL 规则、页面停留时间。不支持计数、序列、缺失条件、时间窗口或不等于
get_trigger_sdk_setup	产品事件代码片段（操作失败、引导、流失）。install_snippet、identify_snippet、allowlist_update_snippet。不包含密钥
list_trigger_events	最近 30 天的产品事件名称。触发器只能使用已观测到的名称
get_trigger_event_schema	单个产品事件的字段、类型和示例值。精确匹配、区分大小写、区分类型
list_studies	现有访谈研究：study_id、interview_link（https://app.usercall.co/interview/...）、interview_mode、trigger_eligible
create_research_trigger	在某个产品时刻（操作失败、流失、引导）之后暂停发送邀请。返回 activation_url
list_research_triggers	列出产品内触发器及其状态和 activation_url
get_research_trigger	单个触发器：邀请对象、activation_url、邀请数和访谈数。不包含主题或引语
update_research_trigger	设置邀请对象。status: "active" 会被拒绝（409）。编辑活动中的触发器会使其暂停
delete_research_trigger	永久删除触发器。已完成的访谈仍保留在研究中

create_research_trigger

Field	Type	Required	Default
study_id	uuid 字符串	是
event_name	字符串（来自 list_trigger_events）	是
properties	精确匹配值对象	否
traits	精确匹配值对象	否
url	{ match: equals | contains | starts_with, value }	否
dwell_seconds	1–600（仅页面访问触发器）	否
source	page_visit | analytics_event | custom	否
sampling_percent	1–100	否	100
cooldown_days	0–365	否	30
max_invites_per_day	1–100	否	100
intercept_title	字符串（≤120），提示词上方的小标签	否	默认
intercept_body	字符串（≤500），提示词文本	否	默认
delivery_method	intercept | webhook	否	intercept
webhook_url	公共 https URL（webhook 必填）	否
webhook_secret	字符串（16–200），HMAC 密钥，仅写入	否
invite_link_params	{ static?, from_traits?, from_properties? }	否
name	字符串（≤100）	否	自动生成

对于页面访问触发器，请使用 source: "page_visit" 和 event_name: "$pageview"，并设置 url，还可选择设置 dwell_seconds。

交付方式。

• intercept（默认）会在你的产品中显示 Usercall 小组件，用户可在页面中进行语音或文本访谈。访谈模式取自研究；list_studies 会返回每项研究的 interview_mode。
• webhook 会将每位匹配用户的信息 POST 到 webhook_url，包括其用户 ID、已知邮箱、特征、事件属性和个人访谈链接。如果设置了 webhook_secret，请求会携带 x-usercall-signature HMAC 标头。
• 仅接受公共 https URL，且激活页面会在用户激活触发器前显示目标地址。

安全

• Agent 无法激活触发器。触发器创建时始终处于暂停状态。调用 update_research_trigger 并设置 status: "active" 会返回 HTTP 409 和 activation_url。用户必须打开该链接，查看邀请对象、他们将看到的内容以及所需额度，然后点击 Activate。
• **对已激活触发器的更改需要重新审批。**更改已激活触发器的配置会使其再次暂停。
• **密钥绝不会返回。**任何工具都不会返回摄取密钥。

---

示例工作流

1. create_study
   key_research_goal: "Why do users drop off during onboarding?"
   business_context: "B2B SaaS, 3-step signup flow"
   target_interviews: 5
   languages: ["ko"]
   interview_mode: "voice"

   → HTTP 201 { study_id, interview_link: "https://app.usercall.co/interview/..." }
   (`business_context` is optional; `key_research_goal` alone still creates a study)

2. simulate_interview
   study_id
   → status "running", simulation_id
   call again with simulation_id
   → pass, fail, or error
   finished transcript: [{ "role": "agent" | "user", "content": "..." }]
   omit persona unless you want a specific one (name 1–80, prompt 1–4000)

3. review_study
   study_id
   → findings, plus suggested_edits (an update_study body, or null)
   send suggested_edits to update_study as-is; nothing is applied for you

4. Share interview_link with participants
   (email, Slack, in-product prompt, etc.)
   share is correct once a terminal simulation or review exists,
   completed interviews are still 0, and any suggested edits are already on the guide

5. get_study_status
   → "not_started" when completed_interviews is 0
   → "running" while an interview is underway
   → next_step "update_study" while a ready review still has unapplied edits

6. get_study_results
   → summary: themes, insights, and risks
   use format=full only for a quote

使用视觉刺激

1. create_study
   key_research_goal: "Get feedback on new dashboard design"
   business_context: "Redesigning analytics dashboard for power users"
   study_media:
     type: "image"
     url: "https://example.com/dashboard-mockup.png"
     description: "New dashboard design concept"

   → returns { study_id, interview_link }

2. After simulate_interview passes, a human shares interview_link. Participants see the mockup during the interview.

对于 Figma 原型，请使用 type: "prototype" 和 Figma 原型 URL。

---

要求

• Node.js 18+
• 有效的 Usercall API 密钥（仅适用于本地 / API 密钥路径）

---

自托管 / 开发

pnpm install
pnpm build
USERCALL_API_KEY="your_key_here" pnpm start

测试和冒烟测试：

pnpm test                                   # unit + MCP contract tests
USERCALL_API_KEY="your_key_here" pnpm smoke # creates a real study
USERCALL_API_KEY="your_key_here" SMOKE_STUDY_ID="<uuid>" SMOKE_EVENT_NAME="<observed event>" pnpm smoke:triggers

---

官方 MCP Registry

Usercall 已作为 co.usercall/mcp 列入官方 MCP Registry。

---

故障排除

错误	修复方法
Missing USERCALL_API_KEY	启动此 stdio 包前设置环境变量
401 Unauthorized	API 密钥无效或已撤销
402 Insufficient credits	打开返回的 checkout_url，或前往 app.usercall.co 充值
500 on create	确认你的密钥有权访问 Agent API v1
event_not_observed	Usercall 尚未收到该事件。将其添加到 SDK 允许列表（get_trigger_sdk_setup(events=[...])），在你的应用中触发该事件，然后重试
wrong_placement	该字段是特征，而非属性（或反之）。按照错误提示使用建议的修复方法
Trait filters never match	在知道用户身份时调用 window.usercall.identify({ userId, traits })（参见 identify_snippet）
webhook_url_not_allowed	使用公开的 https URL，且不包含凭据；不接受 localhost 和私有 IP
409 activation_required	这是预期行为：Agent 无法激活。将 activation_url 分享给用户
429 on simulate_interview	每个账户每天（UTC）最多可进行 5 次模拟。当天请勿继续
Active trigger never fires	检查事件是否仍在到达（list_trigger_events），并确认值完全匹配（大小写和类型）

远程 Claude / ChatGPT / Cursor 连接器应使用 https://mcp.usercall.co（OAuth）。此包使用基于 API 密钥的 stdio 接入方式。

---

许可证

MIT