> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/tools/mcp-apps.md).

# MCP 互動卡片（MCP Apps）

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

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

卡片由 MCP 伺服器決定長什麼樣、能做什麼；MaiAgent 負責把它安全地顯示在對話中、把卡片上的操作轉交給同一個 MCP 伺服器。要讓自家系統提供互動卡片，請工程師參考技術人員手冊的[自架 MCP Server：MCP Apps](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps)與[最小可跑範例](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps-example)。

## 使用者會看到什麼 <a href="#mcp-apps-what-users-see" id="mcp-apps-what-users-see"></a>

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

卡片顯示在 [Web Chat](/build/choose-channel/web-chat.md) 與 [MaiGPT](/work/maigpt.md) 的對話中；LINE、Messenger 等其他通訊平台不顯示卡片，使用者會收到 Agent 的文字回覆。

{% hint style="info" %}
卡片不受[自訂工具訊息顯示](/build/tools/tool-display-settings.md#choose-display-mode)的「顯示模式」影響：即使選擇「隱藏」，互動卡片仍會顯示；「隱藏」只作用在工具執行區塊。
{% endhint %}

### 重新開啟對話時 <a href="#mcp-apps-history" id="mcp-apps-history"></a>

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

* 卡片會以**當時的工具結果**重新顯示；在卡片內填寫到一半的內容、或在卡片內重新查詢後的新結果，不會保留。
* 卡片上的按鈕仍可操作，前提是這個 MCP 工具或連接器仍配置給這段對話、授權仍有效；否則會顯示「這個動作沒有完成，請稍後再試一次。」
* MCP 伺服器之後更新了卡片介面，不會改變歷史訊息中已產生的卡片。

## 需要什麼條件 <a href="#mcp-apps-requirements" id="mcp-apps-requirements"></a>

1. **MCP 伺服器提供互動介面**：工具的定義或回傳結果需附上 `ui://` 開頭的介面資源。是否提供由 MCP 伺服器決定，MaiAgent 這側不需要額外開關。自架 MCP 伺服器的做法見技術人員手冊的[自架 MCP Server](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps)。
2. **Agent 可以使用這個 MCP 伺服器**：以 [MCP 工具](/build/tools/mcp-setup.md)配置給回答模式為 Agent 模式的 Agent，或成員在 MaiGPT 透過[連接器](/work/maigpt/connectors.md)授權使用。
3. **在 Web Chat 或 MaiGPT 中對話**。地端部署的 Web Chat 是否開放互動卡片依部署設定而定，請洽 MaiAgent 窗口確認。

## 適合做成互動卡片的情境 <a href="#mcp-apps-use-cases" id="mcp-apps-use-cases"></a>

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

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

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

## 安全與限制 <a href="#mcp-apps-security" id="mcp-apps-security"></a>

* 卡片在隔離的沙盒框架中執行，無法讀取 MaiAgent 頁面的登入狀態與資料，預設也無法自行連線到外部網站。
* 卡片內的操作只能呼叫該卡片來源 MCP 伺服器、且這段對話已可使用的工具，並沿用 Agent 呼叫該伺服器時的授權方式；單次操作逾 30 秒未回應會視為失敗。
* 卡片要求開啟的外部連結若不被允許，會顯示「這個連結無法開啟。」；被瀏覽器阻擋彈出視窗時，請允許彈出視窗後再試一次。

## 常見問題 <a href="#mcp-apps-faq" id="mcp-apps-faq"></a>

#### 卡片顯示「這個動作沒有完成，請稍後再試一次。」？ <a href="#mcp-apps-action-failed" id="mcp-apps-action-failed"></a>

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

#### 卡片顯示「互動元件載入失敗，請重新整理頁面後再試。」？ <a href="#mcp-apps-load-failed" id="mcp-apps-load-failed"></a>

卡片的介面沒有成功載入。請重新整理頁面，或點擊 <mark style="color:blue;">重試</mark>。卡片一直停在它自己的載入畫面時，也請先重新整理頁面。

#### Agent 呼叫了 MCP 工具，卻沒有出現卡片？ <a href="#mcp-apps-no-card" id="mcp-apps-no-card"></a>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/tools/mcp-apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.