MCP 連携
RooQuiz は MCP(Model Context Protocol)サーバー を提供しており、Claude Desktop、Claude Code、Cursor、Codex などの AI クライアントからチーム内のクイズを操作できます。自然言語で、知識クイズ、スコアクイズ、結果タイプクイズの作成、設問の追加、項目の並べ替え、レポートの次元や結果タイプの設定ができます。さらに、クイズの複製 / 削除、翻訳や回答者の管理、回答記録・統計・コンバージョンファネルの読み取りも行えるため、エディターですべてを手作業で組み立てる必要がなくなります。
MCP は 上級ユーザー 向けの機能で、MCP に対応した AI クライアントが必要です。基本的なクイズを視覚的に作成する場合は、引き続きエディターをおすすめします。
仕組み
- AI クライアントは、2 つの認証方法のいずれかを使って RooQuiz の MCP エンドポイント(
/api/mcp)に接続します。OAuth 認可(推奨。対応クライアントではブラウザでサインインするだけです)または 個人用 API トークン です。 - どちらの方法でも、AI は現在アクティブなチームの中で あなたとして 操作します。
- すべての操作は管理画面と同じ アクセスチェック を通り、書き込み操作は 監査ログ にも記録されます。
- そのため、AI ができることは、そのチームでのあなたのロールと権限の範囲に完全に限定され、それを超えることはできません。
方法 1:OAuth 認可(推奨)
MCP の OAuth に対応したクライアント(claude.ai と Claude Code)では、トークンを手動で作成する必要はありません。エンドポイントの URL を指定するだけで、クライアントが認可サーバーを自動的に検出してブラウザを開きます。そこで RooQuiz にサインインし、認可するチームを選んで「認可」をクリックします。
claude.ai の Settings → Connectors → Add custom connector を開きます。
- 任意の名前を付けます(例:
RooQuiz)。 - リモート MCP サーバーの URL として、エンドポイント(
https://your-domain/api/mcpのような形式)を指定します。 - 保存して「Connect」をクリックすると、ブラウザが 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***[email protected])。マスクは元に戻せないため、マスクされた値をプロンプトに貼り付けるのではなく、回答者を ID で指定してください。
利用できるツール
接続すると、AI アシスタントは以下のツールを呼び出せます。いずれも、トークンが 現在アクティブ になっているチームに対して動作します。
チーム(Tenant)
| ツール | 内容 |
|---|---|
list_my_tenants | 所属するすべてのチームを一覧表示し、現在アクティブなチームを示します。 |
get_active_tenant | トークンが現在アクティブになっているチームを返します。すべての書き込みはデフォルトでこのチームに対して行われます。 |
switch_active_tenant | アクティブなチームを切り替えます(セッションをまたいで保持されます。切り替え先は参加済みのチームである必要があります)。 |
フォーム
| ツール | 内容 |
|---|---|
create_form | クイズ(knowledge_quiz の試験、scored_quiz、または outcome_quiz のタイプ診断)を作成します。設問の配列とレポートの設定を 1 回の呼び出しで渡せるため、何度もやり取りする必要がありません。結果タイプクイズでは、作成時に report.outcomes(結果タイプの一覧)を 必ず 含め、すべての選択肢が outcomes でタイプに投票するようにする必要があります。 |
list_forms | 現在のチームのクイズを一覧表示します。シーンやタイトルで絞り込むこともできます。 |
get_form | クイズの詳細(fields[] の設問一覧、レポートの設定など)をすべて表示します。編集する前にこれを呼び出して、各設問の code を取得してください。結果タイプクイズの場合、結果タイプの code は report.outcomeAnalysis.outcomes にあります。 |
update_form | タイトル、説明、公開/停止の状態を更新するか、report の設定をサブキー単位でマージして置き換えます。結果タイプクイズでは、report.outcomes を渡すと結果タイプを code ごとにマージ更新します(名前 / 説明 / CTA。設定済みの画像は保持され、設問の投票でまだ参照されているタイプを削除しようとすると拒否されます)。シーンと言語は作成後に固定されます。 |
delete_form | クイズをゴミ箱に移動します(ソフトデリート)。list_forms には表示されなくなり、5 日間は restore_form で復元できます(その後は完全に削除されます)。削除できるのはクイズのオーナー / チームのオーナーだけです。回答記録は完全に削除されるまで保持されます。 |
restore_form | delete_form で削除したクイズをゴミ箱から復元します。復元できるのはオーナー / チームのオーナーだけで、ゴミ箱にない場合はエラーになります。 |
duplicate_form | クイズを複製します。設問の構成、採点、レポート、ビジュアル、設定に加えて すべての言語の翻訳 を、あなたがオーナーとなる新しいクイズに複製します(リンクは新しく発行されます)。回答記録、共有、連携、停止状態は複製 しません。newTitle は任意です。 |
設問
| ツール | 内容 |
|---|---|
add_question | 末尾に項目を追加します。設問(SingleCheck/MultiCheck/TrueFalse/FillBlank)または改ページ(Breaker)です。結果タイプクイズでは、すべての選択肢でどの結果タイプに投票するかを宣言する必要があります(TrueFalse では trueOutcomes / falseOutcomes を使います)。 |
insert_question | after / before で既存の code を参照し、指定した位置に項目を挿入します。 |
move_question | 既存の設問または改ページを、code を指定して新しい位置に移動します。 |
update_question | code を指定して、問題文、注記、解説、必須フラグ、配点、正解、または FillBlank の AI 採点を更新します。設問タイプや選択肢の内容は変更できません。 |
delete_question | code を指定して、設問または改ページを削除します。 |
レポートの次元
| ツール | 内容 |
|---|---|
set_dimension_analysis | クイズの多次元分析(レーダーチャートの次元)を一括で設定します。knowledge_quiz では各次元が設問の code を参照し、scored_quiz では各次元が計算式を使います。空の配列を渡すとクリアされます。結果タイプクイズには適用されません(次元がないため、代わりに 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)
クイズに回答する人です。各回答者は 1 つのチームに紐づいています。ツールが返すのは安全な項目だけで、パスワード、認証コード、リセットトークンなどの機密性の高い項目が公開されることは ありません。
| ツール | 内容 |
|---|---|
list_examinees | 現在のチームの回答者を一覧表示します。メールアドレス / 名前によるあいまい検索や、ステータス(有効 / 無効)による絞り込みもできます。 |
get_examinee | ビジネス ID examineeId(例:AB1234567890。一覧に表示されます)を指定して、回答者の詳細(カスタムの customData を含む)を表示します。 |
update_examinee | examineeId を指定して、回答者の名前 / ステータス / customData を編集します(customData はチームのフィールド定義に照らして検証されます)。メールアドレスとチームは変更できません。 |
回答記録と分析
クイズの成果、コンバージョンファネル、リードを読み取り、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 で参照します。 |
典型的な流れ:
- 試験 / スコアクイズ:
create_formでクイズを作成して各設問のcodeを取得 →update_formまたはset_dimension_analysisで、codeを使ってレポートの計算式 / 次元を設定します。 - 結果タイプクイズ:
create_formを 1 回呼び出し、report.outcomes(各タイプに独自の一意なcodeを付けます。例:lion)と各選択肢の投票を渡します → 送信後、最も票を集めたタイプが結果になります(同票の場合は一覧の順で決まります)。タイプの文言 / CTA は後からupdate_formで調整します。
現在の制限
- ランダム知識クイズには対応していません:設問は QuestionBank にあるため、エディターで管理してください。MCP はまだ対応していません。
- 設問タイプや選択肢を直接変更できません:タイプを切り替えたり選択肢を編集したりするには、
delete_questionしてからadd_questionで作り直します。結果タイプクイズの 選択肢から結果タイプへの投票の対応付け も同様で、投票を変更するには設問を作り直します。 - スコアクイズの選択肢の採点 は Option Scoring を使います。スコアクイズのシーンでは、
update_questionはscore/correctAnswer/aiMatchを拒否します。選択肢のスコアは管理画面で編集するか、削除して作り直してください。結果タイプのシーンでも、これら 3 つのパラメーターは同様に拒否されます(投票で結果を決めるため、採点はありません)。 - 結果タイプクイズの設問タイプ:投票に使える設問は SingleCheck / MultiCheck / TrueFalse です(FillBlank には対応していません)。結果タイプの 画像 はまだ MCP からアップロードできないため、エディターで設定してください(MCP で
report.outcomesを更新しても、設定済みの画像は保持されます)。 - シーンと言語は作成後に固定され、MCP から変更することはできません。
- 削除はソフトデリートです:
delete_formはゴミ箱に移動するだけで(5 日後に自動的に完全削除されます)、即座に完全削除されるわけではありません。完全に削除するには、管理画面で再度削除してください。 - 設問数の上限:Free プランでは 1 つのクイズに 50 問 までです(改ページ、説明文、画像カルーセルは含まれません)。それを超えると、
create_form、add_question、insert_questionは拒否されます。duplicate_formとcreate_form_from_templateには制限がありません。Pro では無制限です。設問数の上限をご覧ください。 - 複製ではデータはコピーされません:
duplicate_formが複製するのは構成と翻訳だけで、回答記録、共有設定、連携(シークレットを含む)はコピー されません。新しいクイズはまっさらな状態から始まります。 - 回答者の識別項目は変更できません:
update_examineeでは、メールアドレス、チーム、examineeIdを変更できません(これらは認証上の識別情報です)。 - リードには個人情報が含まれます:
list_records/get_recordは回答者のメールアドレス、名前、カスタムフィールドなどを返します。責任を持って取り扱ってください。 - FillBlank の AI 採点(
aiMatch。知識クイズのシーンのみ、ベータ版)は、チームの AI クレジットを消費します。
セキュリティとレート制限
- OAuth でもトークンでも、AI は あなたとして 操作し、既存のアクセスチェックと 監査ログ の対象になります(すべての書き込みが記録されます)。
- 各接続は 1 分あたり 60 リクエスト に制限されており、超えるとレート制限のエラーが返されます。
- 不要になったら、設定 → MCP連携 で 取り消し(即座に反映されます。OAuth 接続の場合はクライアントとの接続が切断されます)または 削除(枠も空きます)を行ってください。
- OAuth の手順では PKCE(S256) が必須で、認可コードは 1 回限り有効です。リフレッシュトークンは更新のたびにローテーションされ、古いトークンは即座に無効になります。
概要
開発者向けに、自社のコードや AI クライアントから RooQuiz にアクセスする方法を紹介します。アカウント単位の API キーでフォームや回答を取得する REST API と、Claude などの AI クライアントがチーム内のクイズを直接作成・編集できる MCP サーバーの違い、そしてコードを書かずにコネクターで連携する方法と、プッシュとプルの使い分けを説明します。
REST API
チームのフォーム定義(タイトル、設問、設定、レポートの構成)や回答データを JSON で返す、シンプルな読み取り専用の REST API です。スクリプト、Zapier・Make・n8n による自動化、独自のダッシュボードで利用できます。API キーの取得方法、認証、各エンドポイントのパラメーターとレスポンスの例、エラーコード、レート制限について説明します。