MCP 互動卡片（MCP Apps）

MCP 伺服器提供的互動卡片（MCP Apps）在 Web Chat 與 MaiGPT 對話中怎麼呈現、怎麼操作、需要什麼條件、安全限制，以及適合做成互動卡片的情境與常見問題。

有些 MCP 伺服器除了回傳資料，還會附上一份互動介面。Agent 呼叫這類工具後，對話中會出現一張可以直接操作的卡片，例如查詢結果的表格、可以勾選或填寫的表單，讓使用者不必只靠文字往來。

卡片由 MCP 伺服器決定長什麼樣、能做什麼；MaiAgent 負責把它安全地顯示在對話中、把卡片上的操作轉交給同一個 MCP 伺服器。要讓自家系統提供互動卡片，請工程師參考技術人員手冊的自架 MCP Server：MCP Apps與最小可跑範例。

使用者會看到什麼

情境	呈現方式
卡片出現的位置	Agent 回覆完成後，卡片出現在該則回覆下方（回覆還在產生時不會先出現）
載入中	卡片剛出現時顯示的是卡片自己的載入畫面（例如「載入中…」），資料送達後才換成正式內容
同一回合多次呼叫	同一張卡片只顯示最新的狀態，不會重複出現多張相同卡片
在卡片內操作	卡片上的按鈕或表單可以直接查詢、送出資料，結果會更新在同一張卡片中
卡片高度	依卡片內容自動調整；內容超過畫面約六成高度（最高 620px）時改在卡片內捲動
全螢幕	卡片若提供全螢幕按鈕，可展開成全螢幕；點右上角的 ✕（退出全螢幕，回到對話）或按 Esc 回到對話，卡片會維持展開前的高度
從卡片向 AI 提問	卡片若提供提問功能，送出的內容會成為一則使用者訊息出現在對話中，卡片自動收合回對話，由 Agent 接著回答
卡片開啟外部連結	由瀏覽器開新分頁；只開一般網頁、電話與 Email 連結
深色模式與品牌色	平台會把目前的明暗模式與品牌色告知卡片；是否跟著變色由卡片決定
卡片內容無法載入	改以純文字顯示工具回傳的摘要

卡片顯示在 Web Chat 與 MaiGPT 的對話中；LINE、Messenger 等其他通訊平台不顯示卡片，使用者會收到 Agent 的文字回覆。

卡片不受自訂工具訊息顯示的「顯示模式」影響：即使選擇「隱藏」，互動卡片仍會顯示；「隱藏」只作用在工具執行區塊。

重新開啟對話時

卡片的介面與當時的工具結果會隨訊息保存。之後從對話歷史重新開啟這段對話：

• 卡片會以當時的工具結果重新顯示；在卡片內填寫到一半的內容、或在卡片內重新查詢後的新結果，不會保留。

• 卡片上的按鈕仍可操作，前提是這個 MCP 工具或連接器仍配置給這段對話、授權仍有效；否則會顯示「這個動作沒有完成，請稍後再試一次。」

• MCP 伺服器之後更新了卡片介面，不會改變歷史訊息中已產生的卡片。

需要什麼條件

1. MCP 伺服器提供互動介面：工具的定義或回傳結果需附上 ui:// 開頭的介面資源。是否提供由 MCP 伺服器決定，MaiAgent 這側不需要額外開關。自架 MCP 伺服器的做法見技術人員手冊的自架 MCP Server。

2. Agent 可以使用這個 MCP 伺服器：以 MCP 工具配置給回答模式為 Agent 模式的 Agent，或成員在 MaiGPT 透過連接器授權使用。

3. 在 Web Chat 或 MaiGPT 中對話。地端部署的 Web Chat 是否開放互動卡片依部署設定而定，請洽 MaiAgent 窗口確認。

適合做成互動卡片的情境

卡片適合「文字說不清楚、或需要使用者動手」的結果。幾個常見的例子：

情境	卡片做什麼	文字回覆的限制
查詢結果的表格與圖表	訂單、庫存、報表等查詢結果以表格或圖表呈現，可排序或切換區間	多欄位、多筆資料用文字列出不易閱讀
表單填寫	請假單、報修單等欄位直接在卡片中填寫，送出後由同一個 MCP 伺服器建單	一問一答逐欄收集，容易漏填或填錯格式
確認送出	把 Agent 整理好的內容（例如要寄出的通知、要變更的設定）列出來，使用者按「確認」才真正執行	使用者只能用文字回「好」，不易看清楚將執行的內容
地圖、日期或時段選擇	選門市、選預約時段、選座位，點選後卡片把選擇結果交回 Agent	地點與時段用文字描述與比對都不方便

共同原則：卡片只處理這一次工具結果對應的操作；跨多個步驟的流程仍由 Agent 的對話串起來。

安全與限制

• 卡片在隔離的沙盒框架中執行，無法讀取 MaiAgent 頁面的登入狀態與資料，預設也無法自行連線到外部網站。

• 卡片內的操作只能呼叫該卡片來源 MCP 伺服器、且這段對話已可使用的工具，並沿用 Agent 呼叫該伺服器時的授權方式；單次操作逾 30 秒未回應會視為失敗。

• 卡片要求開啟的外部連結若不被允許，會顯示「這個連結無法開啟。」；被瀏覽器阻擋彈出視窗時，請允許彈出視窗後再試一次。

常見問題

卡片顯示「這個動作沒有完成，請稍後再試一次。」？

卡片內的操作呼叫 MCP 伺服器時失敗、逾時，或這個工具已不在這段對話可用的範圍內。點擊 重試 重新載入卡片；若持續發生，請確認 MCP 伺服器運作正常、工具仍配置給 Agent、授權仍有效。

卡片顯示「互動元件載入失敗，請重新整理頁面後再試。」？

卡片的介面沒有成功載入。請重新整理頁面，或點擊 重試。卡片一直停在它自己的載入畫面時，也請先重新整理頁面。

Agent 呼叫了 MCP 工具，卻沒有出現卡片？

該工具的 MCP 伺服器沒有提供互動介面，或這次呼叫回傳錯誤。只有附上 ui:// 介面資源、且成功執行的工具呼叫才會產生卡片；也請確認是在 Web Chat 或 MaiGPT 中查看，而且 Agent 的回覆已經產生完成。