Usercall MCP

Usercall MCP - 実際のユーザーインタビューを実施する AI エージェント

AI は製品を作れます。しかし、まだユーザーと対話することはできません。

AI エージェントが実際のユーザーに理由を尋ねられるようにします。

Usercall MCP は、実際のユーザーを対象に、AI が進行する音声またはテキストのインタビューを実施します。ユーザーが離脱する理由、オンボーディングのどこで離脱するか、あるいは操作に失敗した理由を調べ、テーマ、インサイト、逐語的な引用を得るために活用できます。

このプロジェクトの目的

AI エージェントは、製品を非常に速く構築し、リリースできるようになりました。

しかし、多くのエージェントは依然として、ユーザーに関する合成フィードバックや推測に頼っています。

Usercall MCP を使うと、エージェントは実際のユーザーから直接、定性的なフィードバックを収集できます。

---

接続方法を選択

推奨：ホスト型 MCP（Claude、ChatGPT、Cursor、Grok Bot）

リモート MCP コネクター／カスタムコネクターとして https://mcp.usercall.co を追加します。

• 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 の申請用パッケージです（バージョンは package.json ではなく plugin.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 キー／マシン間通信

スクリプト、ローカルクライアント、M2M などで Bearer API キーを使う場合は、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 エージェント

↓

Usercall MCP（ホスト型 OAuth または この stdio パッケージ）

↓

Usercall Agent API

↓

実際のユーザーインタビュー

↓

テーマと逐語的な引用がエージェントに返される

Research Triggers を使うと、エージェントは製品内のユーザーを対象にすることもできます。

Analytics MCP（PostHog、Mixpanel、…）がユーザーの行動を検出

↓

Usercall MCP が調査と一時停止中の Research Trigger を作成

↓

Usercall で有効化

↓

Usercall SDK が、該当する行動の直後に一致するユーザーをインタビューに招待

---

リサーチトリガー

アナリティクスからは、ユーザーが「何を」しているかがわかります。リサーチトリガーを使えば、「なぜ」そうするのかをユーザーに尋ねられます。

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 を（アナリティクスプロバイダーとイベント名を指定して）呼び出し、コードスニペットを取得してください。コーディングエージェントがインストールを代行できます。
• Usercall が実際に受信したイベントのみ使用できます。 フィルターは、イベントの プロパティ またはユーザーの 特性 と完全一致する必要があります。どのフィールドがどちらにあたるかは、get_trigger_event_schema で確認できます。
• サポートされていない条件は、黙って無視されるのではなく拒否されます。 イベント数、シーケンス、不在（「X をしなかった」）、時間枠、不一致条件などが該当します。全リストは 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 のリモートコネクターを使う場合は、この JSON 設定の代わりに https://mcp.usercall.co を使用してください。

MCP クライアントを再起動します。

3. エージェントに依頼する

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

エージェントは次の処理を行います。

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 が進行するインタビュー調査を作成します。音声、テキスト、または音声とテキストによるインタビュー用の study_id と interview_link を含む HTTP 201 を返します。interview_link は https://app.usercall.co/interview/ URL です。key_research_goal は必須で、後から変更できません。business_context は任意です。デフォルト値：target_interviews は 1、duration_minutes は 12、interview_mode は voice です。1 アカウントにつき、アクティブなエージェント調査は 1 件です。インタビューの実施や参加者への招待は行いません。HTTP 402 には checkout_url が含まれます。

フィールド	型	必須	デフォルト
key_research_goal	string (5–2000)	はい
business_context	string (5–2000)	いいえ
additional_context_prompt	string	いいえ
target_interviews	number (1–200)	いいえ	1
languages	string[]	いいえ
duration_minutes	number (5–65)	いいえ	12
interview_mode	voice | text | voice_and_text	いいえ	voice
voice_gender	female | male	いいえ
enable_link_context	boolean	いいえ
custom_link_variables	{ key, label?, default_value? }[]	いいえ
metadata	object	いいえ
study_media	object	いいえ

ロケールが 1 つの場合は言語選択機能がオフになり、2 つ以上の場合はオンになります。調査の目的は作成後に変更できません。

study_media（任意）。すべてのインタビュー質問中に表示される視覚的な刺激素材です。

フィールド	型	必須
type	image | prototype	はい
url	string (URL)	はい
description	string (max 500 chars)	いいえ

• image：画像の直接 URL（.png、.jpg、.gif、.webp）
• prototype：Figma のプロトタイプ URL（インタラクティブな埋め込みに変換されます）
• メディアはウェブ参加者にのみ表示されます。電話で参加する人には表示されません

update_study

インタビュースタディのスロット、ガイドの質問、イントロ、言語、音声、または参加者に表示する画像やFigmaプロトタイプを更新します。更新されたスタディを返します。key_research_goalは変更できません。is_link_disabledをtrueにすると、新しいインタビューを停止し、録音は保持されます。ロケールが1つの場合は言語選択欄が非表示になり、2つ以上の場合は表示されます。enable_link_contextがtrueになるまで、interview_linkのクエリパラメーターは無視されます。study_mediaにnullを指定すると、メディアが消去されます。APIエラーにはhttp_statusが含まれます。ガイドのドライランや参加者の招待は行いません。

フィールド	型	必須
study_id	uuid string	はい
target_interviews	number (1–200)	いいえ
is_link_disabled	boolean	いいえ
ai_agent_intro_message	string	いいえ
key_learning_goals	string	いいえ
workflow_end_message	string	いいえ
workflow_questions	{ text, ... }[]	いいえ
interview_mode	voice | text | voice_and_text	いいえ
languages	string[]	いいえ
voice_gender	female | male	いいえ
enable_link_context	boolean	いいえ
custom_link_variables	{ key, label?, default_value? }[]	いいえ
study_media	object or 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 string

ステータスの値：not_started · running · analyzing · complete

get_study_results

実際のユーザーへのインタビュー後に、テーマ、インサイト、リスク、逐語的な引用文などの調査結果を取得します。formatを省略するかsummaryを指定すると、テーマ、インサイト、リスクを返します。format=fullを指定すると、トランスクリプトも返します。テーマが空の場合、分析の準備ができていません。インタビューの作成やガイドの編集は行いません。

フィールド	型	必須
study_id	uuid string	はい
format	summary | full	いいえ

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、タイムゾーン、タイムスタンプは返されないため、期待しないでください。アカウントあたり、UTC の1日につき最大5回までシミュレーションできます。HTTP 429 は、1日の上限に達したことを示します。ドライランによって 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 は null です。suggested_edits はそのまま update_study に送信してください。変更は自動適用されません。1クレジットを消費します。リクエストで指定できるのは study_id のみです。call_ids は受け付けません。アプリ内のレビュー操作が非表示の場合でも利用できます。HTTP 402 には checkout_url が含まれます。読み取るのはガイドのみで、トランスクリプトは読み取りません。

フィールド	型	必須
study_id	uuid 文字列	はい

送信するのは study_id のみです。call_ids は送信しません。suggested_edits が null 以外の場合、その値は変更されていない 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	1 つのプロダクトイベントのフィールド、型、サンプル値です。大文字と小文字、型を厳密に区別します
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	1 つのトリガーについて、招待対象者、activation_url、招待数、インタビュー数を返します。テーマや引用は含まれません
update_research_trigger	招待対象者を更新します。status: "active" は拒否されます（409）。有効なトリガーを編集すると一時停止されます
delete_research_trigger	トリガーを完全に削除します。完了済みのインタビューはスタディに残ります

create_research_trigger

フィールド	型	必須	デフォルト
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 は、一致した各ユーザーを webhook_url に POST します。ユーザー ID、判明している場合はメールアドレス、トレイト、イベントプロパティ、個人用インタビューリンクが含まれます。webhook_secret が設定されている場合、リクエストには x-usercall-signature HMAC ヘッダーが含まれます。
• 公開された https URL のみが受け付けられ、アクティベーションページには、トリガーをアクティベートする前に遷移先が表示されます。

安全性

• エージェントはトリガーをアクティベートできません。 トリガーは常に一時停止状態で作成されます。status: "active" を指定して update_research_trigger を呼び出すと、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 プロトタイプには、Figma のプロトタイプ URL とともに type: "prototype" を使用します。

---

要件

• 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 レジストリ

Usercall は、公式 MCP レジストリ に co.usercall/mcp として掲載されています。

---

トラブルシューティング

エラー	対処
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	想定どおりです。エージェントは有効化できません。ユーザーに activation_url を共有してください
429 on simulate_interview	1 アカウントあたりのシミュレーション上限は UTC 日ごとに 5 回です。その日はこれ以上実行しないでください
Active trigger never fires	イベントが引き続き届いているか（list_trigger_events）、また値が完全に一致しているか（大文字と小文字、型）を確認してください

リモートの Claude ／ ChatGPT ／ Cursor コネクターでは、https://mcp.usercall.co（OAuth）を使用してください。このパッケージは API キーを使用する stdio 接続経路です。

---

ライセンス

MIT