外部ツールの開発
Chatbotta のボットが使う外部ツール(MCP サーバー)を開発する方向けのページです。Chatbotta がいつ、誰の権限でツールを呼び出すのか、お客様一人ひとりに本人のデータだけを見せるにはサーバー側で何が必要かを説明します。
外部ツールをインストール・設定するだけなら、アプリをご覧ください。
はじめに:Chatbotta は個人向け AI アシスタントではありません
Section titled “はじめに:Chatbotta は個人向け AI アシスタントではありません”ChatGPT や Claude のような個人向け AI アシスタントが外部ツールに接続する場合、使う人と認可した人は同じです。Chatbotta は違います。外部ツールは事業者がプロジェクトで一度設定し、その後はボットが事業者に代わって、面識のない多くのお客様に返信します。
そのため外部ツールを設計するときに一番大切なのは、その呼び出しが誰の認証情報を使うかです。
- 事業者共通の認証情報:どのお客様が質問しても、ボットは同じ事業者アカウントで照会します。空室、営業時間、在庫など、誰に対しても同じデータに向いています。
- お客様ごとの認証情報:お客様はまずあなたのサービスで本人確認を行い、ボットはそのお客様の代わりに呼び出すとき、そのお客様のトークンだけを送ります。「自分の注文」「自分の予約」「自分のポイント」のように人によって異なるデータに向いており、お客様に自分の予約を取り消したり変更したりさせる場合の唯一安全な方法です。
ボットがツールを呼び出すしくみ
Section titled “ボットがツールを呼び出すしくみ”- お客様 → Chatbotta のボット: LINE、Messenger、Instagram、Web チャットでメッセージを送信
- Chatbotta のボット: 各外部ツールの「Purpose」をもとに、使うかどうか、どれを使うかを判断
- Chatbotta のボット → あなたの MCP サーバー: tools/call(「Bot」列にチェックされたツールのみ)
- あなたの MCP サーバー → Chatbotta のボット: 結果を返す
- Chatbotta のボット → お客様: 通常の返信にまとめる
設計に影響するポイント:
- ツール一覧はキャッシュされます。 外部ツールの追加時(または再読み込み時)に Chatbotta が
tools/listを一度呼び出し、各ツールの名前・説明・入力スキーマを保存します。返信のたびにこのキャッシュを使い、実際にツールを呼び出すときだけサーバーに接続します。ツールを変更したら、管理者に「Settings」›「Copilot and tools」でツール一覧を再読み込みしてもらってください。 - AI があなたのツールを思いつくかは「Purpose」次第です。 管理者が入力する「Purpose」は、AI が外部ツールを選ぶときに見る唯一の説明です。選んだあとで初めて、各ツールの説明とスキーマを見ます。
- Copilot とボットは別々の一覧です。 管理者はツール一覧の「Copilot」列と「Bot」列を別々にチェックします。お客様との会話に出てくるのは「Bot」にチェックしたツールだけで、先に「Copilot」にチェックする必要があります。追加直後は Copilot だけが使えます。
- 接続していなければ呼び出されません。 ステータスが「Connected」以外(「Needs authorization」「Connection error」など)のあいだ、AI はそのツールを呼び出しません。
- 通信方式:Streamable HTTP を使い、接続できない場合は SSE を使います。呼び出しのたびに新しく接続し、セッションは保持しません。
認証方式の選び方
Section titled “認証方式の選び方”管理者は「Add external tool」で「Authentication」を選びます。作成後は変更できないため、変えるには削除して追加し直します。
| 認証方式 | 呼び出しに使う認証情報 | Copilot | ボット | 向いている用途 |
|---|---|---|---|---|
| No authentication (public server) | なし | 可 | 可 | 公開データ |
| OAuth (authorize in the browser) | 事業者(管理者が一度認可) | 可 | 可 | 空室や在庫など事業者単位のデータ |
| API token / bearer token | 事業者(管理者が貼り付けたトークンを暗号化して保存) | 可 | 可 | 同上(サーバーが OAuth に対応していない場合) |
| Each customer authorizes (OAuth per user) | お客様ごとのトークン | 不可 | 1 対 1 の会話のみ | 「自分の注文」など人によって異なるデータ |
「OAuth」では、管理者が Chatbotta のポップアップで認可します。リダイレクト URI は https://app.chatbotta.com/oauth/mcp/callback です。Chatbotta はリフレッシュトークンを保存し、自動で更新します。
お客様ごとの認証(OAuth per user)
Section titled “お客様ごとの認証(OAuth per user)”お客様が会話の中で初めてそのツールを必要としたとき、ボットは認可ボタンを送ります。お客様があなたのページで本人確認を終えると、Chatbotta はそのお客様専用のアクセストークンを受け取り、以降そのチャットからの呼び出しには毎回そのトークンを付けます。
- お客様 → Chatbotta: 「前回予約した部屋は何日でしたか?」
- Chatbotta → あなたの MCP サーバー: 接続(このお客様のトークンはまだない)
- あなたの MCP サーバー → Chatbotta: 401 + WWW-Authenticate(resource_metadata)
- Chatbotta → あなたの認可サーバー: 認可サーバーのメタデータを取得し、クライアントを動的登録
- Chatbotta → お客様: 会話の中で認可ボタンを送信(PKCE と state 付き)
- お客様 → あなたの認可サーバー: あなたのページで本人確認し、認可に同意
- あなたの認可サーバー → Chatbotta: code と state を付けて Chatbotta へリダイレクト
- Chatbotta → あなたの認可サーバー: code と code_verifier をアクセストークンに交換
- Chatbotta → あなたの MCP サーバー: tools/call(Authorization: Bearer このお客様のトークン)
- Chatbotta → お客様: 先ほどの質問への返信を自動で続ける
お客様が認可を終えるとブラウザに完了ページが表示され、Chatbotta は先ほどのメッセージへの返信を自動で続けます。お客様が会話に戻って同じ質問をし直す必要はありません。
サーバーに必要なもの
Section titled “サーバーに必要なもの”MCP の認可仕様どおりに実装してください。Chatbotta は公式の MCP SDK でこの流れを実行します。
-
MCP エンドポイント:Streamable HTTP(または SSE)。トークンがない、または無効なリクエストには
401を返し、WWW-Authenticateヘッダーのresource_metadataで保護リソースメタデータ(RFC 9728)を示してください。ない場合は/.well-known/oauth-protected-resourceを参照します。 -
認可サーバーメタデータ(RFC 8414):
/.well-known/oauth-authorization-server。 -
動的クライアント登録(RFC 7591)。Chatbotta は次の内容で登録します。
{"client_name": "Chatbotta","redirect_uris": ["https://api.chatbotta.com/api/mcp/customerOAuth/callback"],"grant_types": ["authorization_code", "refresh_token"],"response_types": ["code"],"token_endpoint_auth_method": "none"} -
認可コード + PKCE(S256):Chatbotta はパブリッククライアントで、client secret は送りません。保護リソースメタデータがある場合、認可リクエストとトークンリクエストに
resourceパラメーター(RFC 8707)を付けます。 -
リダイレクト URI:
https://api.chatbotta.com/api/mcp/customerOAuth/callback(codeとstate付き)。
サーバーが動的登録に対応していない場合、管理者は追加時に「Use a manually registered OAuth app (the server doesn’t support automatic registration)」にチェックし、Client ID、Client secret、Authorization URL、Token URL を入力できます。この場合 Chatbotta は認可 URL を直接組み立て(response_type、client_id、redirect_uri、state。scope と PKCE は付けません)、コード交換時は client_id と client_secret をフォームの本文で送ります。リダイレクト URI は同じです。
本人確認とセキュリティ
Section titled “本人確認とセキュリティ”- Chatbotta はお客様の身元を送りません。 お客様の LINE ユーザー ID、名前、電話番号は届かず、どのお客様かを判断できるのはトークンだけです。そのため認可ページでは、電話番号への SMS 認証やあなたのサービスの会員ログインなどで、お客様の本人確認を必ず行ってください。
- 本人の判断はトークンだけで行います。 ツールの引数に含まれる会員番号や電話番号で、誰のデータを返すかを決めないでください。引数は AI が入力するもので、お客様が会話の中で他人の情報を入れるよう AI に頼むこともできます。
- 認可ページはチャットアプリの内蔵ブラウザで開きます(LINE など)。お客様の多くはスマートフォンからアクセスし、あなたのサイトにログインしたこともありません。スマートフォンと内蔵ブラウザで最後まで操作できることを確認してください。
- トークンは「このチャット × この外部ツール」に紐づき、暗号化して保存されます。同じ人が LINE と Web チャットの両方から問い合わせると 2 つのチャットになるため、それぞれで認可が必要です。
- トークンは自動で更新されません。 期限が切れると、次に必要になったときに Chatbotta がお客様に再認可を依頼します。トークンレスポンスに
expires_inを含め、セキュリティ要件に合った有効期限を設定してください。あなたが失効させたトークンは、期限が切れるまで呼び出しに失敗します。 - 管理者がサーバー URL を変更すると、すべてのお客様のトークンが削除されます。トークンが新しいホストへ送られることはありません。
- ツールの結果にトークンが含まれていた場合、Chatbotta は会話ログに保存する前に伏せ字にします。それでも、結果に認証情報を含めないでください。
- 1 対 1 の会話でのみ使えます。 LINE のグループや複数人のチャットでは、誰が質問しているか特定できないため、このツールは表示されません。
- Copilot からは呼び出せません。 Copilot は管理者向けで、対応するお客様がいないためです。管理用のツールが必要な場合は、事業者の認証情報を使う外部ツールを別に追加してください。
- 同じサービスを 2 回追加できます:Copilot での管理用に「OAuth」のものを 1 つ、ボットがお客様に返信する用に「Each customer authorizes」のものを 1 つ。両者の権限は完全に分かれています。
追加後のツール一覧
Section titled “追加後のツール一覧”この方式には事業者単位の認証情報がないため、追加直後はツール一覧を取得できず、ステータスは「No customer has verified yet」になります。
-
管理者が外部ツールのカードで「Test connection」を選び、新しいタブで自分のアカウントを使って認可を一度行います。
-
認可が完了すると、Chatbotta は取得したトークンで
tools/listを呼び出し、ステータスが「Connected」になり、すべてのツールが自動でボットに公開されます(どの呼び出しもお客様本人の権限の範囲に限られるためです)。「Copilot and tools」に戻って「Refresh status」を選ぶとツール一覧が表示されます。公開したくないツールは「Bot」列のチェックを外してください。 -
その後ツールを変更したら、ツール一覧を再読み込みします。Chatbotta は認可済みのお客様 1 人のトークンを借りて
tools/listを呼び出し、それ以外の用途には使いません。
「Test connection」を行わなかった場合も、最初のお客様が認可した時点でツール一覧を取得します。ただしそれまではステータスが「Connected」にならず、ボットはこのツールを使いません。
お客様への情報の問い合わせ(elicitation)
Section titled “お客様への情報の問い合わせ(elicitation)”ツールの実行中に、お客様から追加の情報が必要だとわかった場合は、MCP の elicitation/create(form モード)を使えます。これは「Each customer authorizes」の外部ツールでのみ機能します。
ほとんどの情報はツールの引数で十分で、elicitation は不要です。 注文番号、日付、人数のような「今回何を調べるか」を示す情報は、入力スキーマに必須項目として定義すれば、AI が先にお客様に尋ねて引数に入れます。
elicitation が向いているのは次のような情報です。
- 特定の場合にだけ必要:尋ねるかどうかは、サーバーがデータを確認するまでわからない。たとえば注文作成時に、このお客様の配送先住所がまだ登録されていないとわかったときだけ尋ね、登録済みのお客様には尋ねません。
- 記憶して自動で使いたい:回答はチャットごとに記憶され、以降同じフィールドの elicitation には記憶した値で回答するため、お客様が毎回伝え直す必要がありません。
- AI に入力させたくない:回答はお客様自身のメッセージからそのまま取られるため、AI が言い換えたり推測したり別の値に置き換えたりできません。
会話は非同期です。お客様の回答は後の別のメッセージで届くため、Chatbotta はツールの呼び出しを待たせておけません。そこで、いったん断ってボットがお客様に尋ね、次の呼び出しで回答します。
- Chatbotta → あなたの MCP サーバー: tools/call create_order
- あなたの MCP サーバー → Chatbotta: elicitation/create:「配送先住所を教えてください」(フィールド shipping_address)
- Chatbotta → あなたの MCP サーバー: decline(このチャットにはまだ shipping_address がない)
- Chatbotta → お客様: 自然な言い方で配送先住所を尋ねる
- お客様 → Chatbotta: 「台北市信義区松仁路 100 号」
- Chatbotta: このメッセージを shipping_address として保存(暗号化)
- Chatbotta → あなたの MCP サーバー: もう一度 tools/call create_order
- あなたの MCP サーバー → Chatbotta: elicitation/create(同じフィールド)
- Chatbotta → あなたの MCP サーバー: accept:shipping_address = お客様のメッセージ
- あなたの MCP サーバー → Chatbotta: 注文結果を返す
実装時の注意:
- 一度に尋ねるのは 1 フィールドだけです。
requestedSchema.propertiesに 2 つ以上のフィールドがあると、Chatbotta は decline します。 - URL モード(
mode: "url")には対応しておらず、常に decline します。お客様に Web ページで操作してもらう場合は認可の流れを使ってください。 - 保存されるのはお客様のメッセージ全体で、必要な部分だけではありません。「台北市信義区松仁路 100 号に送ってください」のように返ってくることもあるため、サーバー側で抽出・検証し、形式が合わなければもう一度 elicit するか、わかりやすいエラーを返してください。
- decline を受け取ったら、その呼び出しは普通に終了してください(結果でもエラーでもかまいません)。待ち続けないでください。Chatbotta はその結果を無視し、ボットにお客様へ尋ねさせます。
- 回答はチャットごとに記憶され、以降同じフィールド名の elicitation には記憶した値で回答します。フィールド名は変えず、意味の異なるデータに同じフィールド名を使わないでください。
ツール設計のヒント
Section titled “ツール設計のヒント”- ツールの説明は AI 向けに書きます:いつ使うか、必要な引数、返す内容をはっきり書いてください。AI は呼び出すかどうかも引数の入れ方も、この説明だけで判断します。
- 引数はサーバー側で検証します:Chatbotta はスキーマから
formatとpatternを取り除きますが、型と必須項目はチェックします。値が不正な場合は「日付は YYYY-MM-DD 形式で指定してください」のような短くわかりやすいエラーを返すと、AI が修正して再試行します。 - 結果は簡潔に:Chatbotta は
contentをテキストにして AI に渡します。回答に必要な項目だけを返し、元データを丸ごと返さないでください。 - 1 つのツールに 1 つの役割:「空室照会」「注文作成」「注文取消」を分けておくと、管理者は安全なツールだけをボットに公開できます。
- データを変更する操作は確認できるように:たとえば注文を作成する前に概要を返し、AI がお客様に確認できるようにします。
開発とテスト
Section titled “開発とテスト”-
自分のプロジェクトの「Settings」›「Copilot and tools」›「Add external tool」でサーバー URL を追加します。開発中のサーバーは、トンネリングサービスなどを使ってインターネットから接続できるようにしておく必要があります。
-
「Each customer authorizes」の場合は「Test connection」を選び、自分のアカウントで認可し(スマートフォンでも完了できるか確認してください)、「Refresh status」を選びます。
-
ツール一覧の「Bot」列で公開するツールにチェックし、「Save」を選びます。
-
右側パネルの「Test」で、あなたのツールが必要な質問をします。テスト用の会話は独立した 1 対 1 のチャットなので、「Each customer authorizes」のツールは実際のお客様と同じように認可ボタンを送ります。
ボットがツールを使わない場合は、ステータスが「Connected」か、「Bot」にチェックが入っているか、「Purpose」にいつ使うかがはっきり書かれているかを順に確認してください。