外部工具開發說明
寫給要開發外部工具(MCP 伺服器)讓 Chatbotta 機器人使用的開發者:Chatbotta 什麼時候、用誰的身分呼叫你的工具,以及要讓每位客人只看到自己的資料時,你的伺服器需要提供什麼。
只想安裝或設定外部工具的話,看應用程式就夠了。
先了解:Chatbotta 不是個人 AI 助理
Section titled “先了解:Chatbotta 不是個人 AI 助理”ChatGPT、Claude 這類個人 AI 助理連接外部工具時,使用的人和授權的人是同一個人。Chatbotta 不一樣:外部工具由商家在專案裡設定一次,之後由機器人代替商家,回覆許多不認識的客人。
所以設計外部工具時,最重要的問題是:這次呼叫用的是誰的憑證?
- 商家共用的憑證:每位客人問問題,機器人都用同一組商家帳號去查。適合查空房、查營業時間、查商品庫存這類對每位客人都一樣的資料。
- 每位客人自己的憑證:每位客人先在你的服務完成驗證,機器人替這位客人呼叫時只帶這位客人的權杖。適合查「我的訂單」「我的預約」「我的點數」這類因人而異的資料,也是要讓客人取消或修改自己資料時唯一安全的做法。
機器人怎麼呼叫你的工具
Section titled “機器人怎麼呼叫你的工具”- 客人 → Chatbotta 機器人: 在 LINE、Messenger、Instagram 或網站聊天傳訊息
- Chatbotta 機器人: 依每個外部工具的「用途說明」判斷要不要用、用哪一個
- Chatbotta 機器人 → 你的 MCP 伺服器: tools/call(只會呼叫「機器人」欄有勾選的工具)
- 你的 MCP 伺服器 → Chatbotta 機器人: 回傳結果
- Chatbotta 機器人 → 客人: 整理成一般的回覆
幾件會影響你設計的事:
- 工具清單是快取的。 新增外部工具(或按「重新整理」)時,Chatbotta 呼叫一次
tools/list,把工具名稱、說明與 input schema 存下來。之後每次回覆都直接用這份快取,只有真正呼叫工具時才連線到你的伺服器。工具有異動時,請管理者到「設定」›「小助手與工具」重新整理工具清單。 - 「用途說明」決定 AI 會不會想到你的工具。 管理者填的「用途說明」是 AI 選擇外部工具時看到的唯一說明;選中之後,AI 才會看到各工具的說明與 schema。
- 小助手和機器人是兩份清單。 管理者在工具清單的「小助手」與「機器人」兩欄分別勾選;只有勾選「機器人」的工具會出現在回覆客人的對話中,而且一定要先勾選「小助手」。新增時預設只開放給小助手。
- 沒有連線就不會呼叫。 外部工具的狀態不是「已連線」時(例如「待授權」「連線錯誤」),AI 不會呼叫它的工具。
- 連線方式:使用 Streamable HTTP,連不上時改用 SSE。每次呼叫都是新的連線,不會保留 session。
選擇驗證方式
Section titled “選擇驗證方式”管理者在「新增外部工具」選「驗證方式」。驗證方式建立後不能修改,要換就得刪除後重新新增。
| 驗證方式 | 呼叫時用誰的憑證 | 小助手 | 機器人 | 適合 |
|---|---|---|---|---|
| 不需驗證(公開伺服器) | 無 | 可以 | 可以 | 公開資料 |
| OAuth(開啟瀏覽器授權) | 商家(管理者授權一次) | 可以 | 可以 | 商家層級的資料,例如空房、庫存 |
| API Token / Bearer Token | 商家(管理者貼上的權杖,加密儲存) | 可以 | 可以 | 同上,伺服器不支援 OAuth 時 |
| 每位客人各自授權(OAuth Per-User) | 每位客人自己的權杖 | 不行 | 只限一對一對話 | 因人而異的資料,例如「我的訂單」 |
「OAuth」模式的授權由管理者在 Chatbotta 後台的彈出視窗完成,回傳網址是 https://app.chatbotta.com/oauth/mcp/callback;Chatbotta 會保存 refresh token 並自動續期。
每位客人各自授權(OAuth Per-User)
Section titled “每位客人各自授權(OAuth Per-User)”每位客人在對話中第一次需要這個工具時,機器人會傳一個授權按鈕給客人;客人在你的頁面完成驗證後,Chatbotta 取得只屬於這位客人的 access token,之後這間聊天室的每次呼叫都帶著它。
- 客人 → Chatbotta: 「我上次訂的房間是哪天?」
- Chatbotta → 你的 MCP 伺服器: 連線(還沒有這位客人的權杖)
- 你的 MCP 伺服器 → Chatbotta: 401 + WWW-Authenticate(resource_metadata)
- Chatbotta → 你的授權伺服器: 讀取授權伺服器 metadata、動態註冊用戶端
- Chatbotta → 客人: 在對話中傳出授權按鈕(含 PKCE 與 state)
- 客人 → 你的授權伺服器: 在你的頁面驗證身分、同意授權
- 你的授權伺服器 → Chatbotta: 帶 code 與 state 轉回 Chatbotta
- Chatbotta → 你的授權伺服器: 用 code 與 code_verifier 換 access token
- Chatbotta → 你的 MCP 伺服器: tools/call,Authorization: Bearer 這位客人的權杖
- Chatbotta → 客人: 自動接著回覆剛才的問題
客人完成授權後,瀏覽器會顯示「完成」的頁面;Chatbotta 會自動接著回覆剛才那則訊息,客人不需要回到對話再問一次。
你的伺服器需要提供
Section titled “你的伺服器需要提供”照 MCP 授權規格實作即可,Chatbotta 使用官方 MCP SDK 走這套流程:
-
MCP 端點:Streamable HTTP(或 SSE)。請求沒有權杖或權杖無效時回
401,並在WWW-Authenticate帶resource_metadata指向受保護資源 metadata(RFC 9728);沒有帶的話,會改查/.well-known/oauth-protected-resource。 -
授權伺服器 metadata(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"} -
Authorization Code + PKCE(S256):Chatbotta 是公開用戶端,不帶 client secret。受保護資源 metadata 存在時,授權與換權杖的請求會帶
resource參數(RFC 8707)。 -
回傳網址:
https://api.chatbotta.com/api/mcp/customerOAuth/callback,帶回code與state。
伺服器不支援動態註冊的話,管理者可以在新增時勾選「使用手動註冊的 OAuth 應用程式」,填入用戶端 ID、用戶端密鑰、授權網址與權杖網址。這時 Chatbotta 直接組授權網址(response_type、client_id、redirect_uri、state,不帶 scope 與 PKCE),換權杖時把 client_id 與 client_secret 放在表單內容送出。回傳網址相同。
- Chatbotta 不會把客人的身分傳給你。 你不會收到客人的 LINE 使用者 ID、姓名或電話,權杖是你判斷「這是哪位客人」的唯一依據。所以你的授權頁必須自己驗證客人,例如寄簡訊驗證碼到手機、或請客人登入你的會員帳號。
- 只從權杖判斷身分。 不要信任工具參數裡的會員編號、電話等欄位來決定要回傳誰的資料:參數是 AI 填的,客人可以在對話裡要求 AI 填別人的。
- 授權頁會在聊天 App 的內建瀏覽器開啟(例如 LINE),客人多半用手機、也沒有登入過你的網站。請確認頁面在手機與內建瀏覽器都能完成流程。
- 權杖綁定「這間聊天室 × 這個外部工具」,加密儲存。同一個人分別從 LINE 和網站聊天來問,會是兩間聊天室,需要各授權一次。
- 權杖到期後不會自動續期,Chatbotta 會在下次需要時請客人重新授權。請在權杖回應中帶
expires_in,並依你的安全需求設定有效期限;你撤銷的權杖,在到期前呼叫會失敗。 - 管理者改了伺服器網址,所有客人的權杖都會清除,權杖永遠不會送到新的主機。
- 工具回傳結果中如果出現權杖,Chatbotta 會先遮蔽再寫入對話紀錄;仍請不要在結果裡回傳任何憑證。
- 只在一對一對話中使用。 LINE 群組、多人聊天室不會出現這類工具,因為無法確定是哪位客人在問。
- 小助手不能呼叫。 小助手是給管理者用的,沒有對應的客人;需要管理用工具的話,另外新增一個用商家憑證的外部工具。
- 同一個服務可以新增兩次:一個用「OAuth」給小助手管理、一個用「每位客人各自授權」給機器人回覆客人,兩者的權限完全分開。
新增後的工具清單
Section titled “新增後的工具清單”這個模式沒有商家層級的憑證,剛新增時拿不到工具清單,狀態會是「還沒有客人完成驗證」。
-
管理者在外部工具的卡片按「測試連線」,在新分頁用自己的帳號走一次授權流程。
-
授權完成時,Chatbotta 用剛取得的權杖呼叫
tools/list,狀態變成「已連線」,所有工具會自動開放給機器人(每次呼叫都已經限定在客人自己的權限內)。回到「小助手與工具」按「重新整理狀態」就會看到工具清單;不想開放的工具,可以在「機器人」欄取消勾選。 -
之後工具有異動時按「重新整理」:Chatbotta 會借用一位已授權客人的權杖呼叫
tools/list,只用來取得工具清單。
沒有按「測試連線」的話,第一位客人完成授權時也會自動取得工具清單;但在那之前狀態不是「已連線」,機器人不會使用這個工具。
向客人詢問資料(elicitation)
Section titled “向客人詢問資料(elicitation)”工具執行到一半,才發現需要客人補充資料時,可以用 MCP 的 elicitation/create(form 模式)。這只在「每位客人各自授權」的外部工具中有效。
大多數資料放在工具參數就好,不需要 elicitation。 訂單編號、日期、人數這類「這次要查什麼」的資料,寫進 input schema 並標為必填,AI 會自己先問客人、再把答案填進參數。
適合用 elicitation 的情況:
- 只有某些情況才需要:要不要問,得等伺服器查過資料才知道。例如建立訂單時發現這位客人還沒有收件地址,才回頭要;已經有地址的客人就不用問。
- 要記住、之後自動帶入:答案會記在這間聊天室,之後同一欄位的 elicitation 直接用記住的值回答,客人不必每次重講。
- 不想經過 AI 填寫:elicitation 的答案直接取自客人自己的訊息,不會被 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: 回傳訂單結果
實作時請注意:
- 一次只問一個欄位。
requestedSchema.properties超過一個欄位時,Chatbotta 會直接 decline。 - 不支援 URL 模式(
mode: "url"),一律 decline。要客人到網頁操作,請用授權流程。 - 存下來的是客人整則訊息,不是只有你要的那段。客人可能回「寄到台北市信義區松仁路 100 號,謝謝」,請在伺服器端擷取、驗證格式,格式不對時再 elicit 一次或回傳清楚的錯誤。
- 收到 decline 時請正常結束這次呼叫(回傳結果或錯誤都可以),不要等待。Chatbotta 會忽略這次的結果,改請機器人詢問客人。
- 答案會記在這間聊天室,之後同一欄位名稱的 elicitation 會直接用記住的值回答。欄位名稱請保持穩定,不同意義的資料不要共用欄位名稱。
工具設計建議
Section titled “工具設計建議”- 工具說明寫給 AI 看:寫清楚什麼時候用、需要哪些參數、會回傳什麼。AI 只靠這些文字決定要不要呼叫、怎麼填參數。
- 在伺服器端驗證參數:Chatbotta 會先移除 schema 裡的
format與pattern,型別與必填欄位仍會檢查。格式不對時請回傳簡短、看得懂的錯誤訊息(例如「日期要是 YYYY-MM-DD」),AI 會依此修正後重試。 - 結果要精簡:Chatbotta 把
content轉成文字交給 AI。只回傳回答問題需要的欄位,不要整份原始資料。 - 一個工具做一件事:「查空房」「建立訂單」「取消訂單」分開,管理者才能只開放安全的工具給機器人。
- 會修改資料的動作要能確認:例如建立訂單前先回傳摘要,讓 AI 跟客人確認。
-
在自己的專案用「設定」›「小助手與工具」›「新增外部工具」加入你的伺服器網址。開發中的伺服器需要可以從網際網路連到,例如用通道服務暴露本機。
-
「每位客人各自授權」的話,按「測試連線」用自己的帳號走一次授權,確認授權頁在手機上也能完成,再按「重新整理狀態」。
-
在工具清單的「機器人」欄勾選要開放的工具,按「儲存」。
-
在右側面板的「測試」問一個需要你工具的問題。測試對話是一間獨立的一對一聊天室,「每位客人各自授權」的工具會在這裡傳出授權按鈕,跟真實客人的流程相同。
機器人沒有使用你的工具時,依序檢查:狀態是否「已連線」、「機器人」欄是否勾選、「用途說明」是否寫清楚什麼時候該用。