MCP 連携
RooQuiz は MCP(Model Context Protocol)サーバー を提供しており、ChatGPT、claude.ai、Claude Desktop、Claude Code、Cursor、Codex などの AI クライアントからチーム内の作業を行えます。自然言語で、テンプレートからまたは一から行うクイズの作成、設問の追加と編集、レポートの次元や結果タイプの設定、配信設定の変更と共有リンクの取得、翻訳や回答者の管理、リードへの対応、予約・回答記録・統計・コンバージョンファネルの読み取りができるため、エディターですべてを手作業で行う必要がなくなります。
RooQuiz には AI でクイズを自動生成する機能は組み込まれていません。AI でクイズを作成したい場合は、MCP で 自分の AI クライアント を接続して依頼してください。AI は以下のツールを使って作成し、その結果をエディターで確認できます。
MCP は 上級ユーザー 向けの機能で、MCP に対応した AI クライアントが必要です。基本的なクイズを視覚的に作成する場合は、引き続きエディターをおすすめします。
仕組み
- AI クライアントは、2 つの認証方法のいずれかを使って RooQuiz の MCP エンドポイント(
/api/mcp)に接続します。OAuth 認可(推奨。対応クライアントではブラウザでサインインするだけです)または 個人用 API トークン です。 - どちらの方法でも、AI は現在アクティブなチームの中で あなたとして 操作します。
- すべての操作は管理画面と同じ アクセスチェック を通り、書き込み操作は 監査ログ にも記録されます。
- そのため、AI ができることは、そのチームでのあなたのロールと権限の範囲に完全に限定され、それを超えることはできません。
方法 1:OAuth 認可(推奨)
MCP の OAuth に対応したクライアント(ChatGPT、claude.ai、Claude Code)では、トークンを手動で作成する必要はありません。エンドポイントの URL を指定するだけで、クライアントが認可サーバーを自動的に検出してブラウザを開きます。そこで RooQuiz にサインインし、認可するチームを選んで「認可」をクリックします。
RooQuiz は ChatGPT のアプリとして利用できます。RooQuiz の管理画面上部にある ChatGPT で使う をクリックして開き、接続します。ブラウザが RooQuiz の認可ページにリダイレクトされるので、サインインし、チームを選んで「認可」をクリックします。
OAuth 接続について:
- 認可時に選んだチームが最初のアクティブなチームになります。AI は後から
switch_active_tenantで切り替えることもできます。 - 接続は 設定 → MCP連携 のトークン一覧に(OAuth タグ付きで)表示されます。取り消すと、そのクライアントとの接続が切断されます。5 個のトークン上限には 含まれません。
- 認証情報は自動的に更新されます(アクセストークンは 1 時間ごとにローリング方式で更新され、接続自体は 30 日間有効で、使用するたびに延長されます)。手動で管理する必要はありません。
方法 2:個人用トークン(PAT)
OAuth に対応していないクライアント(Cursor、Codex CLI、Claude Desktop)や、CI などブラウザのない環境では、個人用 API トークンで接続します。
トークンを作成する
設定 → MCP連携 に移動し、トークンを作成 をクリックします。
- トークン名 を付けます(識別用。例:
Cursor - my Mac)。 - 初期チーム を選びます。トークンはデフォルトでこのチームを操作し、AI は後から
switch_active_tenantツールで、あなたが所属するほかのチームに切り替えられます。 - 作成後、
rqp_live_で始まる平文のトークンが表示されます。
平文のトークンは一度だけ表示されます。 ページを離れると取得し直すことはできません。すぐにコピーしてください。紛失した場合は、取り消して新しいトークンを作成する必要があります。
制限:
- 各ユーザーが保持できるトークンは 最大 5 個 です(取り消し済みのものを含み、OAuth 接続は含みません)。さらに作成するには、いずれかを 削除 して枠を空けてください(「取り消し」は無効化するだけで、枠は空きません)。取り消した個人用トークンは 有効化 で再び使えるようにできます。
- トークンは 個人の認証情報 です。ソース管理にコミットしたり、公開の場で共有したりしないでください。
AI クライアントを設定する
設定 → MCP連携 ページでは、クライアントごとにすぐに使える設定スニペットと、エンドポイントURL(https://your-domain/api/mcp のような形式)をコピーできます。スニペット内の rqp_live_xxx... を、生成したトークンに置き換えてください。
Claude Code では上記の OAuth の手順をおすすめします。トークンのヘッダーが必要なのは、CI などブラウザのない環境だけです。
claude mcp add --transport http rooquiz https://your-domain/api/mcp \
--header "Authorization: Bearer rqp_live_xxx..."プロンプトの例
クライアントを接続したら、普段の言葉で話しかけてください。以下の例は、それぞれサーバーの異なる部分を使います。
テンプレートから作成する
コーチング向けのテンプレートを見せて。準備度診断のテンプレートからスコアクイズを作成して、予算に関する設問を 2 つ追加して。
list_templates → create_form_from_template → add_question を使います。
リードに対応する
今週、Wheel of Life クイズで獲得したリードを一覧にして、スコアが 40 未満の人全員に「要フォロー」のタグを付け、私に割り当てて。
list_leads → set_lead_tags → assign_leads を使います。
ファネルを診断する
私のクイズの中で完了率が最も低いのはどれ? 具体的にどこで離脱している?
list_forms → get_form_stats → get_form_funnel を使います。
多言語化する
昇進準備度クイズを、設問コードを維持したままスペイン語とドイツ語に翻訳して。
list_form_translations → create_form_translation を使います。
回答者の名前、メールアドレス、電話番号は マスクされた状態 で返されます(j***g@example.com)。マスクは元に戻せないため、マスクされた値をプロンプトに貼り付けるのではなく、回答者を ID で指定してください。
利用できるツール
接続すると、AI アシスタントは以下の 44 個のツールを呼び出せます。いずれも、トークンが 現在アクティブ になっているチームに対して動作します。
チーム(Tenant)
| ツール | 内容 |
|---|---|
list_my_tenants | 所属するすべてのチームを一覧表示し、現在アクティブなチームを示します。 |
get_active_tenant | トークンが現在アクティブになっているチーム(チームのアドレスを含む)を返します。すべての書き込みはデフォルトでこのチームに対して行われます。 |
switch_active_tenant | アクティブなチームを切り替えます(セッションをまたいで保持されます。切り替え先は参加済みのチームである必要があります)。 |
invite_member | メールアドレスを指定して、アクティブなチームにメンバーまたは管理者として招待します。参加用リンクを含む招待メールが送信されます。オーナー / 管理者のみ実行できます。 |
update_tenant_slug | チームのアドレス(プラットフォームのドメインでの、すべてのクイズのリンクの最初のパス)を変更します。オーナー / 管理者のみ実行できます。すべての公開クイズのリンクが一斉に移動し、古いアドレスは使えなくなります。/a/<token> のリンクは引き続き使えます。 |
テンプレート
| ツール | 内容 |
|---|---|
list_templates | 公開テンプレートライブラリにある有効なテンプレート(タイトル、シーン、説明、カテゴリ、利用回数)を、利用回数の多い順に一覧表示します。 |
create_form_from_template | テンプレートから 1 回の呼び出しで新しいクイズを作成します。構成、採点 / レポートの設定、ビジュアルの設定、すべての言語バージョンが含まれます。適したテンプレートがある場合は、これが最も手早い作成方法です。 |
フォーム
| ツール | 内容 |
|---|---|
create_form | クイズ(knowledge_quiz、scored_quiz、または outcome_quiz のタイプ診断)を作成します。設問の配列とレポートの設定を 1 回の呼び出しで渡せるため、何度もやり取りする必要がありません。結果タイプクイズでは、作成時に report.outcomes(結果タイプの一覧)を 必ず 含め、すべての選択肢が outcomes でタイプに投票するようにする必要があります。 |
list_forms | 現在のチームのクイズを、新しい順に一覧表示します。設問の内容は含まれません。 |
get_form | クイズの詳細(fields[] の設問一覧、レポートの設定など)をすべて表示します。編集する前にこれを呼び出して、各設問の code を取得してください。結果タイプクイズの場合、結果タイプの code は report.outcomeAnalysis.outcomes にあります。 |
update_form | タイトル、説明、公開/停止の状態、カバー(flagImg / landingImage)、テーマ、ソーシャル用のシェアカード(openGraph)、システム文言を更新するか、report の設定をサブキー単位でマージして置き換えます。結果タイプクイズでは、report.outcomes を渡すと結果タイプを code ごとにマージ更新します(設定済みの画像は保持され、設問の投票でまだ参照されているタイプを削除しようとすると拒否されます)。言語 を変更できるのはクイズに言語バージョンがない間だけで、シーン は変更できません。 |
delete_form | クイズをゴミ箱に移動します(ソフトデリート)。list_forms には表示されなくなり、5 日間は restore_form で復元できます(その後は完全に削除されます)。チームのどのメンバーでも削除できます。回答記録は完全に削除されるまで保持されます。 |
restore_form | delete_form で削除したクイズをゴミ箱から復元します。 |
duplicate_form | クイズを複製します。設問の構成、採点、レポート、ビジュアル、設定に加えて すべての言語の翻訳 を、あなたがオーナーとなる新しいクイズに複製します(リンクは新しく発行されます)。回答記録、連携、停止状態は複製 しません。newTitle は任意です。 |
共有と配信の設定
| ツール | 内容 |
|---|---|
get_form_share_info | クイズの公開に必要なものをまとめて返します。公開の回答リンク(言語バージョンごとのリンクも含む)、チームのカスタムドメインとそれが稼働中かどうか、3 つのモード(inline / popup / iframe)の埋め込みスニペット、現在の配信設定です。utmSource を渡すと、すべてのリンクとスニペットに 1 つのチャネル用のタグが付きます。 |
update_form_settings | クイズの配信方法を変更します。誰が回答できるか、レポートの閲覧にメールアドレス(リード獲得のゲート)と確認コードが必要かどうか、制限時間(知識クイズ)、共有とシェアカード、解答用紙、みんなとの比較、結果ページの予約セクションとその Cal.com リンク、フィードバックのブロック、PDF ダウンロード(Pro)、Google アナリティクスの ID などを設定できます。 |
設問
| ツール | 内容 |
|---|---|
add_question | 末尾に項目を追加します。設問、改ページ(Breaker)、または表示用のブロック(Statement のリッチテキスト、Swiper の画像カルーセル)です。設問タイプは SingleCheck / MultiCheck / TrueFalse、FillBlank、DropDown、Ordering(知識クイズ)、NumberField と Rate(スコアクイズ)です。結果タイプクイズでは、すべての選択肢でどの結果タイプに投票するかを宣言する必要があります(TrueFalse では trueOutcomes / falseOutcomes を使います)。 |
insert_question | after / before で既存の code を参照し、指定した位置に項目を挿入します。 |
move_question | 既存の設問または改ページを、code を指定して新しい位置に移動します。 |
update_question | code を指定して設問を更新します。問題文、注記、解説、必須フラグ、配点、正解、FillBlank の AI 採点、数値 / 日付 / 評価のオプションを変更でき、選択式の設問では 選択肢をまとめて置き換え られます。表示用のブロックもここで編集します。設問タイプは変更できません。 |
delete_question | code を指定して、設問または改ページを削除します。 |
レポートの次元
| ツール | 内容 |
|---|---|
set_dimension_analysis | クイズの多次元分析(レーダーチャートの次元)を一括で設定します。次元があるのは scored_quiz のみで、各次元は設問の code を参照する計算式を使います(知識クイズには次元がありません)。空の配列を渡すとクリアされます。結果タイプクイズには適用されません(次元がないため、代わりに report.outcomes で結果タイプを設定します)。 |
翻訳(FormTranslation)
クイズを複数の言語で提供します。1 つのソースのクイズ(主要言語)と、ほかの言語ごとに 1 つの翻訳で構成されます(構成はソースと同じで、テキストだけが翻訳されます。回答記録は常にソースのクイズに紐づきます)。
| ツール | 内容 |
|---|---|
create_form_translation | クイズに言語バージョンを追加します。ソースの文言を初期の下書きとして複製し(code は同じで、テキストはソース言語のまま)、その内容を返すので、すぐに翻訳に取りかかれます。言語は主要言語と異なる必要があり、言語ごとに 1 つまでです。 |
list_form_translations | クイズの既存の言語バージョン(言語、有効フラグ、公開リンクなど)を一覧表示します。 |
get_form_translation | 1 つの言語バージョンの全内容(fields[] と report を含む)を読み取り、その場で翻訳できるようにします。すべての code はソースと同一のままでなければなりません。 |
update_form_translation | 言語バージョンの翻訳済みの文言(title / description / fields / report / systemText)を保存するか、isActive で一時停止します。構成はソースで決まっており、変更できるのはテキストだけです。省略した項目は部分的な翻訳として扱われます。 |
delete_form_translation | 1 つの言語バージョンを削除します。 |
回答者(examinees)
クイズに回答する人です。管理画面では「回答者」と呼ばれますが、ツールでは examinee という名称のままです。各回答者は 1 つのチームに紐づいています。ツールが返すのは安全な項目だけで、パスワード、認証コード、リセットトークンなどの機密性の高い項目が公開されることは ありません。
| ツール | 内容 |
|---|---|
list_examinees | 現在のチームの回答者を一覧表示します。メールアドレス / 名前によるあいまい検索や、ステータス(有効 / 無効)による絞り込みもできます。 |
get_examinee | ビジネス ID examineeId(例:AB1234567890。一覧に表示されます)を指定して、回答者の詳細(カスタムの customData を含む)を表示します。 |
update_examinee | examineeId を指定して、回答者の名前 / ステータス / customData を編集します(customData はチームのフィールド定義に照らして検証され、オブジェクト全体が置き換えられます)。メールアドレスとチームは変更できません。 |
リード
| ツール | 内容 |
|---|---|
list_leads | チームのリードを一覧表示します。すべてのクイズを通じて回答者 1 人につき 1 件で、フォローアップのステータス、担当者、カラータグ、回答数、次回の予約が含まれます。ステータス / 担当者 / タグ / 作成日 / キーワード / 今後の予約で絞り込めます。 |
get_lead | leadId を指定して 1 件のリードを表示します。回答者の回答履歴、チームの社内コメント、変更のタイムラインも併せて取得できます。 |
list_lead_settings | チームのフォローアップのステータス、タグのライブラリ、割り当て可能なメンバーを読み取ります。ステータスのコード、タグのコード、メンバーの ID はチームごとに異なるため、書き込みの前に呼び出してください。 |
update_lead | 1 件のリードを別のフォローアップのステータスに移動します(例:new → contacted)。リードのタイムラインに記録されます。 |
assign_leads | 1 回の呼び出しで最大 50 件のリードを、有効なメンバーに割り当てます(自分の場合は "me")。担当者の解除もできます。担当者には通知がまとめて 1 件届きます。 |
set_lead_tags | 1 回の呼び出しで最大 50 件のリードにカラータグを設定します。replace(1 件のリード)のほか、一括処理では add / remove を使うと、ほかの人が付けたタグが残ります。 |
add_lead_comment | リードに社内向けのフォローアップのコメントを書き込みます(チーム内のみで、回答者には表示されません)。特定の回答に紐づけることもできます。 |
予約
| ツール | 内容 |
|---|---|
list_bookings | Cal.com から同期されたチームの予約を、日時の早い順に一覧表示します。日時、ステータス、Cal.com のイベントタイプ、参加者、発生元のクイズと回答、リードの担当者が含まれます。ステータス / クイズ / 回答者 / 期間で絞り込めます。読み取り専用で、予約の変更は Cal.com で行います。 |
回答記録と分析
クイズの成果と回答を読み取り、AI が「作成 → 計測 → 改善」のサイクルを回せるようにします。
| ツール | 内容 |
|---|---|
get_form_stats | 直近 N 日間(デフォルトは 30、最大 180)のクイズの統計を読み取ります。KPI の概要、日別の推移、チャネル(utm_source)、ログインの種類、デバイス、設問ごとの回答分布が含まれます。 |
get_form_funnel | 直近 N 日間のクイズのコンバージョンファネルを読み取ります。閲覧 → 開始 → 回答 → リード獲得 → レポート閲覧 → CTA クリック → 共有の各段階に加え、チャネル別のファネルと離脱ポイントが含まれます。 |
list_records | 現在のチームの回答記録を一覧表示します。回答者、回答内容、簡潔なレポートの結果、UTM が含まれ、クイズ、レポートのステータス、送信日時で絞り込めます。 |
get_record | id(list_records が返します)を指定して、1 件の回答記録の詳細を表示します。回答内容の全体、レポートの結果、送信時のメタデータが含まれます。 |
画像のアップロード
| ツール | 内容 |
|---|---|
prepare_image_upload | ステップ 1:カバーや画像のための直接アップロード用 URL を発行します(ファイルをその URL に PUT します)。 |
finalize_image_upload | ステップ 2:画像を検証してチームのメディアライブラリに登録し、メディア ID を返します。update_form の flagImg / landingImage で参照します。 |
典型的な流れ:
- テンプレートから:
list_templates→create_form_from_template→update_form/update_questionで調整します。 - 試験 / スコアクイズ:
create_formでクイズを作成して各設問のcodeを取得 →update_formまたはset_dimension_analysisで、codeを使ってレポートの計算式 / 次元を設定します。 - 結果タイプクイズ:
create_formを 1 回呼び出し、report.outcomes(各タイプに独自の一意なcodeを付けます。例:lion)と各選択肢の投票を渡します → 送信後、最も票を集めたタイプが結果になります(同票の場合は一覧の順で決まります)。タイプの文言 / CTA は後からupdate_formで調整します。 - 公開:
update_form_settingsでリード獲得のゲートと結果ページのセクションを設定 →get_form_share_infoでリンクと埋め込みコードを取得します。
現在の制限
- 設問タイプは変更できません:タイプを切り替えるには、
delete_questionしてからadd_questionで作り直します。選択肢はupdate_questionでまとめて置き換えられますが、TrueFalse の結果タイプへの投票(trueOutcomes/falseOutcomes)を変更するには、引き続き削除して作り直す必要があります。 - シーンごとの採点:スコアクイズと結果タイプクイズのシーンでは、
update_questionはトップレベルのscore/correctAnswer/aiMatchを拒否します。代わりに、choices[i].score(Option Scoring)またはchoices[i].outcomes(投票)を持つ選択肢を渡してください。 - シーンごとの設問タイプ:Ordering は知識クイズ専用、Rate はスコアクイズ専用です。スコアクイズの FillBlank はデータを収集するだけです。結果タイプクイズで使えるのは SingleCheck / MultiCheck / DropDown / TrueFalse(と改ページ、表示用のブロック)です。
- 結果タイプの画像:結果タイプの 画像 はまだ MCP からアップロードできないため、エディターで設定してください(MCP で
report.outcomesを更新しても、設定済みの画像は保持されます)。 - シーンは作成後に固定されます。言語 を変更できるのは、クイズに言語バージョンがない間だけです。
- 削除はソフトデリートです:
delete_formはゴミ箱に移動するだけで(5 日後に自動的に完全削除されます)、即座に完全削除されるわけではありません。完全に削除するには、管理画面で再度削除してください。 - 設問数の上限:Free プランでは 1 つのクイズに 50 問 までです(改ページ、リッチテキスト、画像カルーセルは含まれません)。それを超えると、
create_form、add_question、insert_questionは拒否されます。duplicate_formとcreate_form_from_templateには制限がありません。Pro では無制限です。設問数の上限をご覧ください。 - 複製ではデータはコピーされません:
duplicate_formが複製するのは構成と翻訳だけで、回答記録と連携(シークレットを含む)はコピー されません。新しいクイズはまっさらな状態から始まります。 - 回答者の識別項目は変更できません:
update_examineeでは、メールアドレス、チーム、examineeIdを変更できません(これらは認証上の識別情報です)。 - 個人情報はマスクされて返されます:リード、予約、回答者、回答記録のツールは、名前、メールアドレス、電話番号をマスクして返します。回答の中に入力されたメールアドレスや電話番号も同様です。マスクは元に戻せないため、人物は
examineeId、leadId、回答記録の id で指定してください。
セキュリティとレート制限
- OAuth でもトークンでも、AI は あなたとして 操作し、既存のアクセスチェックと 監査ログ の対象になります(すべての書き込みが記録されます)。
- 各接続は 1 分あたり 60 リクエスト に制限されており、超えるとレート制限のエラーが返されます。
- 不要になったら、設定 → MCP連携 で 取り消し(即座に反映されます。OAuth 接続の場合はクライアントとの接続が切断されます)または 削除(枠も空きます)を行ってください。
- OAuth の手順では PKCE(S256) が必須で、認可コードは 1 回限り有効です。リフレッシュトークンは更新のたびにローテーションされ、古いトークンは即座に無効になります。
概要
開発者向けに、自社のコードや AI クライアントから RooQuiz にアクセスする方法を紹介します。アカウント単位の API キーでフォームや回答を取得する REST API と、自分の AI クライアントからクイズを作成し、リードに対応したり予約を確認したりできる MCP サーバーの違い、そしてコードを書かずにコネクターで連携する方法と、プッシュとプルの使い分けを説明します。
REST API
チームのフォーム定義(タイトル、設問、設定、レポートの構成)や回答データを JSON で返す、シンプルな読み取り専用の REST API です。スクリプト、Zapier・Make・n8n による自動化、独自のダッシュボードで利用できます。API キーの取得方法、認証、各エンドポイントのパラメーターとレスポンスの例、エラーコード、レート制限について説明します。