跳到內容
免費開始使用

外部工具開發說明

寫給要開發外部工具(MCP 伺服器)讓 Chatbotta 機器人使用的開發者:Chatbotta 什麼時候、用誰的身分呼叫你的工具,以及要讓每位客人只看到自己的資料時,你的伺服器需要提供什麼。

只想安裝或設定外部工具的話,看應用程式就夠了。

先了解:Chatbotta 不是個人 AI 助理

Section titled “先了解:Chatbotta 不是個人 AI 助理”

ChatGPT、Claude 這類個人 AI 助理連接外部工具時,使用的人和授權的人是同一個人。Chatbotta 不一樣:外部工具由商家在專案裡設定一次,之後由機器人代替商家,回覆許多不認識的客人。

所以設計外部工具時,最重要的問題是:這次呼叫用的是誰的憑證?

  • 商家共用的憑證:每位客人問問題,機器人都用同一組商家帳號去查。適合查空房、查營業時間、查商品庫存這類對每位客人都一樣的資料。
  • 每位客人自己的憑證:每位客人先在你的服務完成驗證,機器人替這位客人呼叫時只帶這位客人的權杖。適合查「我的訂單」「我的預約」「我的點數」這類因人而異的資料,也是要讓客人取消或修改自己資料時唯一安全的做法。
  1. 客人 → Chatbotta 機器人: 在 LINE、Messenger、Instagram 或網站聊天傳訊息
  2. Chatbotta 機器人: 依每個外部工具的「用途說明」判斷要不要用、用哪一個
  3. Chatbotta 機器人 → 你的 MCP 伺服器: tools/call(只會呼叫「機器人」欄有勾選的工具)
  4. 你的 MCP 伺服器 → Chatbotta 機器人: 回傳結果
  5. Chatbotta 機器人 → 客人: 整理成一般的回覆
客人的一則訊息需要外部資料時

幾件會影響你設計的事:

  • 工具清單是快取的。 新增外部工具(或按「重新整理」)時,Chatbotta 呼叫一次 tools/list,把工具名稱、說明與 input schema 存下來。之後每次回覆都直接用這份快取,只有真正呼叫工具時才連線到你的伺服器。工具有異動時,請管理者到「設定」›「小助手與工具」重新整理工具清單。
  • 「用途說明」決定 AI 會不會想到你的工具。 管理者填的「用途說明」是 AI 選擇外部工具時看到的唯一說明;選中之後,AI 才會看到各工具的說明與 schema。
  • 小助手和機器人是兩份清單。 管理者在工具清單的「小助手」與「機器人」兩欄分別勾選;只有勾選「機器人」的工具會出現在回覆客人的對話中,而且一定要先勾選「小助手」。新增時預設只開放給小助手。
  • 沒有連線就不會呼叫。 外部工具的狀態不是「已連線」時(例如「待授權」「連線錯誤」),AI 不會呼叫它的工具。
  • 連線方式:使用 Streamable HTTP,連不上時改用 SSE。每次呼叫都是新的連線,不會保留 session。

管理者在「新增外部工具」選「驗證方式」。驗證方式建立後不能修改,要換就得刪除後重新新增。

驗證方式 呼叫時用誰的憑證 小助手 機器人 適合
不需驗證(公開伺服器) 無 可以 可以 公開資料
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,之後這間聊天室的每次呼叫都帶著它。

  1. 客人 → Chatbotta: 「我上次訂的房間是哪天?」
  2. Chatbotta → 你的 MCP 伺服器: 連線(還沒有這位客人的權杖)
  3. 你的 MCP 伺服器 → Chatbotta: 401 + WWW-Authenticate(resource_metadata)
  4. Chatbotta → 你的授權伺服器: 讀取授權伺服器 metadata、動態註冊用戶端
  5. Chatbotta → 客人: 在對話中傳出授權按鈕(含 PKCE 與 state)
  6. 客人 → 你的授權伺服器: 在你的頁面驗證身分、同意授權
  7. 你的授權伺服器 → Chatbotta: 帶 code 與 state 轉回 Chatbotta
  8. Chatbotta → 你的授權伺服器: 用 code 與 code_verifier 換 access token
  9. Chatbotta → 你的 MCP 伺服器: tools/call,Authorization: Bearer 這位客人的權杖
  10. Chatbotta → 客人: 自動接著回覆剛才的問題
客人第一次用到「每位客人各自授權」的工具

客人完成授權後,瀏覽器會顯示「完成」的頁面;Chatbotta 會自動接著回覆剛才那則訊息,客人不需要回到對話再問一次。

照 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」給小助手管理、一個用「每位客人各自授權」給機器人回覆客人,兩者的權限完全分開。

這個模式沒有商家層級的憑證,剛新增時拿不到工具清單,狀態會是「還沒有客人完成驗證」。

  1. 管理者在外部工具的卡片按「測試連線」,在新分頁用自己的帳號走一次授權流程。

  2. 授權完成時,Chatbotta 用剛取得的權杖呼叫 tools/list,狀態變成「已連線」,所有工具會自動開放給機器人(每次呼叫都已經限定在客人自己的權限內)。回到「小助手與工具」按「重新整理狀態」就會看到工具清單;不想開放的工具,可以在「機器人」欄取消勾選。

  3. 之後工具有異動時按「重新整理」:Chatbotta 會借用一位已授權客人的權杖呼叫 tools/list,只用來取得工具清單。

沒有按「測試連線」的話,第一位客人完成授權時也會自動取得工具清單;但在那之前狀態不是「已連線」,機器人不會使用這個工具。

工具執行到一半,才發現需要客人補充資料時,可以用 MCP 的 elicitation/create(form 模式)。這只在「每位客人各自授權」的外部工具中有效。

大多數資料放在工具參數就好,不需要 elicitation。 訂單編號、日期、人數這類「這次要查什麼」的資料,寫進 input schema 並標為必填,AI 會自己先問客人、再把答案填進參數。

適合用 elicitation 的情況:

  • 只有某些情況才需要:要不要問,得等伺服器查過資料才知道。例如建立訂單時發現這位客人還沒有收件地址,才回頭要;已經有地址的客人就不用問。
  • 要記住、之後自動帶入:答案會記在這間聊天室,之後同一欄位的 elicitation 直接用記住的值回答,客人不必每次重講。
  • 不想經過 AI 填寫:elicitation 的答案直接取自客人自己的訊息,不會被 AI 改寫、猜測或替換成別的值。

對話是非同步的:客人的回答會在之後另一則訊息才到,Chatbotta 無法讓你的工具呼叫等待。所以流程是先拒絕、讓機器人問客人、下一次呼叫再回答:

  1. Chatbotta → 你的 MCP 伺服器: tools/call create_order
  2. 你的 MCP 伺服器 → Chatbotta: elicitation/create:「請提供收件地址」(欄位 shipping_address)
  3. Chatbotta → 你的 MCP 伺服器: decline(這間聊天室還沒有 shipping_address)
  4. Chatbotta → 客人: 用自然的方式詢問收件地址
  5. 客人 → Chatbotta: 「台北市信義區松仁路 100 號」
  6. Chatbotta: 把這則訊息存成 shipping_address(加密)
  7. Chatbotta → 你的 MCP 伺服器: 再次 tools/call create_order
  8. 你的 MCP 伺服器 → Chatbotta: elicitation/create(同一個欄位)
  9. Chatbotta → 你的 MCP 伺服器: accept:shipping_address = 客人的那則訊息
  10. 你的 MCP 伺服器 → Chatbotta: 回傳訂單結果
建立訂單時發現客人還沒有收件地址

實作時請注意:

  • 一次只問一個欄位。 requestedSchema.properties 超過一個欄位時,Chatbotta 會直接 decline。
  • 不支援 URL 模式(mode: "url"),一律 decline。要客人到網頁操作,請用授權流程。
  • 存下來的是客人整則訊息,不是只有你要的那段。客人可能回「寄到台北市信義區松仁路 100 號,謝謝」,請在伺服器端擷取、驗證格式,格式不對時再 elicit 一次或回傳清楚的錯誤。
  • 收到 decline 時請正常結束這次呼叫(回傳結果或錯誤都可以),不要等待。Chatbotta 會忽略這次的結果,改請機器人詢問客人。
  • 答案會記在這間聊天室,之後同一欄位名稱的 elicitation 會直接用記住的值回答。欄位名稱請保持穩定,不同意義的資料不要共用欄位名稱。
  • 工具說明寫給 AI 看:寫清楚什麼時候用、需要哪些參數、會回傳什麼。AI 只靠這些文字決定要不要呼叫、怎麼填參數。
  • 在伺服器端驗證參數:Chatbotta 會先移除 schema 裡的 format 與 pattern,型別與必填欄位仍會檢查。格式不對時請回傳簡短、看得懂的錯誤訊息(例如「日期要是 YYYY-MM-DD」),AI 會依此修正後重試。
  • 結果要精簡:Chatbotta 把 content 轉成文字交給 AI。只回傳回答問題需要的欄位,不要整份原始資料。
  • 一個工具做一件事:「查空房」「建立訂單」「取消訂單」分開,管理者才能只開放安全的工具給機器人。
  • 會修改資料的動作要能確認:例如建立訂單前先回傳摘要,讓 AI 跟客人確認。
  1. 在自己的專案用「設定」›「小助手與工具」›「新增外部工具」加入你的伺服器網址。開發中的伺服器需要可以從網際網路連到,例如用通道服務暴露本機。

  2. 「每位客人各自授權」的話,按「測試連線」用自己的帳號走一次授權,確認授權頁在手機上也能完成,再按「重新整理狀態」。

  3. 在工具清單的「機器人」欄勾選要開放的工具,按「儲存」。

  4. 在右側面板的「測試」問一個需要你工具的問題。測試對話是一間獨立的一對一聊天室,「每位客人各自授權」的工具會在這裡傳出授權按鈕,跟真實客人的流程相同。

機器人沒有使用你的工具時,依序檢查:狀態是否「已連線」、「機器人」欄是否勾選、「用途說明」是否寫清楚什麼時候該用。