自架 MCP Server 接入規格

把自家系統做成 MCP Server 讓 MaiAgent 的 Agent 呼叫：支援的傳輸方式與 URL 要求、驗證（固定標頭、聯絡人憑證、OAuth 動態註冊）、允許的工具、逾時重試與錯誤如何回給模型，以及 MCP Apps 互動卡片。

本頁寫給要「把自家系統包成 MCP Server，讓 MaiAgent 的 Agent 呼叫」的工程師：MaiAgent 這一端怎麼連你的 Server、帶哪些標頭、怎麼做 OAuth、抓工具清單與呼叫工具時的逾時、重試與錯誤處理。

• MCP 的概念與運作原理請看 MCP（Model Context Protocol）；託管型服務（Composio、Zapier 等）請看 Remote MCP 服務概述。

• 後台的逐步操作（在哪個畫面新增 MCP 工具、每個欄位填什麼）請看使用者手冊的 建立 MCP 工具，本頁不重複操作步驟。

• 若你要接的是一般 REST API 而不是 MCP Server，請看 API 工具工程指南。

一次呼叫的流程

MaiAgent 是 MCP Client；Agent 只負責決定呼叫哪個工具與參數，實際連線由平台送出。

傳輸方式與 URL 要求

項目	規格
支援的傳輸	Streamable HTTP 與 SSE。不支援 stdio（不會在平台上啟動 npx、node 等本機指令）。
傳輸判斷	依 URL 自動判斷：路徑結尾為 /sse、路徑中含 /sse/，或 query string 帶 transport=sse 時走 SSE；其餘一律走 Streamable HTTP。
URL scheme	必須是 https://。只有當目標解析到平台允許的內部網段（部署設定的內部 CIDR 白名單）時才接受 http://。
網路位置	網域必須可解析；解析到私有、loopback 等內部位址會被拒絕（位址落在內部 CIDR 白名單內者除外）；link-local（如 169.254.x.x）一律拒絕，白名單也無法放行。SaaS 環境下，你的 Server 需要能從公網存取。
TLS	預設使用嚴格的憑證驗證。若憑證鏈使用缺少 Subject Key Identifier 的舊版根憑證而連不上，這個放寬選項只能由 MaiAgent 在系統管理端逐一工具或逐一網域開啟，請聯繫 MaiAgent。

建議使用 Streamable HTTP，並把 MCP 端點放在獨立路徑（例如 https://mcp.example.com/mcp）。若你的 Server 只提供 SSE，URL 請以 /sse 結尾，平台才會用 SSE 連線。

建立工具時的連線驗證

在後台或透過 API 建立／更新 MCP 工具時，平台會先實際連到你的 Server 執行一次 tools/list：

• 連不上或拿不到工具清單時，建立會失敗，錯誤訊息會附上連線錯誤內容。

• 若請求沒有指定 mcpAllowedTools 或傳空陣列 []，平台會把當下 tools/list 回傳的所有工具名稱存成允許清單。之後 Server 新增的工具不會自動開放，要回到工具設定重新取得清單並勾選。

• 驗證連線只帶 rawMcpHeader 中不含 {{變數}} 的標頭（這時還沒有對話可以代入變數）。若你的 Server 要求每個請求都必須帶某個動態標頭，請讓 tools/list 在只有固定標頭時也能回應。

• 若這個 URL 對應到設定為 OAuth 的 MCP Registry（見 OAuth 2.0），建立或更新時會略過驗證、允許清單先留空，等授權完成後再取得工具清單。

驗證方式

平台透過 HTTP 標頭把身分帶給你的 Server。帶哪些標頭取決於工具的授權對象（API 欄位 authSubject）：

authSubject	後台名稱	誰的身分	帶入的標頭（後者覆蓋前者同名標頭）
shared（預設）	組織共用	全組織一組授權	工具層 OAuth 權杖 → rawMcpHeader → 該聯絡人的 MCP 憑證
contact	聯絡人個別授權	對話中的聯絡人本人	rawMcpHeader → 該聯絡人的 MCP 憑證 → 該聯絡人的 OAuth 權杖

contact 模式下，匿名聯絡人（沒有 sourceId）的對話中完全不會提供這個工具給 Agent。

固定標頭（API Key）

最簡單的做法：在工具的 rawMcpHeader 放一個 JSON 物件，每次連線都會帶上。

{
  "Authorization": "Bearer <your-api-key>",
  "X-Tenant": "{{organization_id}}"
}

• rawMcpHeader 為唯寫欄位，讀取工具時只會回傳遮罩後的 rawMcpHeaderMasked。

• 值支援以下 {{變數}}，依當下對話代入：contact_id、source_id、contact_name、conversation_id、inbox_id、organization_id、agent_slug、agent_version。

聯絡人層級 MCP 憑證

要讓 Agent 以終端使用者本人的權限呼叫你的 Server，把使用者的權杖寫進該聯絡人的 MCP 憑證：

• 每個聯絡人對每個 MCP 工具最多一筆憑證，內容是一組 headers。

• 對話進行時，平台依「目前對話的聯絡人＋這個工具」找出憑證，把 headers 原樣合併進請求標頭，同名時覆蓋 rawMcpHeader。憑證標頭不做 {{變數}} 代入。

• 寫入方式：

  • Web Chat 嵌入時呼叫 setup-contact-credentials，在 mcpCredentials 帶 toolId 與 headers（toolId 必須是 MCP 類型工具，否則回 400）。

  • 由你的後端呼叫聯絡人 API 的 mcp-credentials 端點新增、更新或刪除。

兩種寫法的完整參數、Token 更新與登出撤銷流程請看 聯絡人身分同步與 Token 更新；後台手動設定見使用者手冊的 聯絡人 MCP 憑證設定。

對話識別標頭

只要有對話情境，平台會在每個請求加上 X-Conversation-Id: <對話 ID>，讓有狀態的 Server 能以對話為單位保存工作狀態，不必依賴模型自己傳一個 session token。若你的驗證標頭剛好同名，以驗證標頭為準。

OAuth 2.0

若你的 MCP Server 以 OAuth 保護，平台會自動完成下列流程（依 MCP 授權規格）：

1

探索受保護資源

平台先不帶權杖對 MCP URL 送一個 GET。若回 401 且 WWW-Authenticate: Bearer resource_metadata="..."，就讀取這個網址（必須是 https，且主機必須與 MCP URL 相同）。否則依 RFC 9728 預設位置嘗試：先 https://{host}/.well-known/oauth-protected-resource{MCP 路徑}，再 https://{host}/.well-known/oauth-protected-resource。

從中取得 resource（權杖的 audience）與 authorization_servers（取第一個，必須是 https）。探索結果快取 5 分鐘。

2

讀取授權伺服器中繼資料

依 RFC 8414 讀取 /.well-known/oauth-authorization-server。授權伺服器 URL 帶路徑時，會依序嘗試「well-known 插在主機與路徑之間」、「well-known 接在路徑後面」、「主機根目錄」三個位置。

3

動態註冊 Client（RFC 7591）

中繼資料有 registration_endpoint 時，平台送出：

{
  "client_name": "MaiAgent MCP Client",
  "redirect_uris": ["<MaiAgent callback URL>"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

沒有 registration_endpoint 時，需在 MCP Registry 預先設定 oauthClientId（機密 client 另設 oauthClientSecret），否則授權會失敗。

4

授權碼＋PKCE

授權請求帶 response_type=code、state、code_challenge（S256）與 resource。scope 的取用順序：MCP Registry 設定的 scope → 受保護資源中繼資料的 scopes_supported → 授權伺服器中繼資料的 scopes_supported。state 有效 10 分鐘。

換權杖時以 grant_type=authorization_code 帶 code_verifier 與 resource，有 client secret 才一併帶上。

5

自動更新權杖

權杖到期前 60 秒內，平台以 grant_type=refresh_token 更新。回應沒有新的 refresh_token 時沿用舊的。

Callback URL：若你的授權伺服器不支援動態註冊、需要預先登記 redirect URI，下列兩個都要登記，否則對應的流程會在 /authorize 失敗：

流程	Callback URL
成員（組織共用）授權	MaiAgent 後台網域 + /oauth/mcp/callback
聯絡人個別授權	https://api.maiagent.ai/api/mcp/oauth/contacts/callback/（SaaS；私有部署依該環境的 API 網域）

MCP Registry：自架 Server 若需要固定 oauthClientId、指定授權伺服器 URL 或 resourceIdentifier，可由具連接器管理權限的成員建立組織私有的 MCP Registry（/api/v1/mcp/private-registry/）。authType 可選 oauth、service_account（以標頭帶金鑰）或 none。平台以「MCP URL 開頭符合 Registry 的 remoteMcpUrl」判斷工具對應哪個 Registry，留空的欄位才會用自動探索的結果。

允許的工具（mcpAllowedTools）

mcpAllowedTools 是 Server 工具名稱的陣列，決定哪些工具會交給 Agent。執行時，儲存的值依授權對象解讀如下：

值	shared	contact
null	開放 Server 所有工具	開放 Server 所有工具
[]（空陣列）	一個都不開放	開放 Server 所有工具
["search_orders", ...]	只開放列出的工具	只開放列出的工具

contact 模式把空陣列視為全部開放，是因為管理員手上沒有聯絡人的權杖、無法事先取得工具清單。shared 模式搭配 OAuth 時，要在管理員完成授權並取得工具清單後，清單才會有內容。

透過 API 建立或更新工具時：

• 一般 MCP 工具：不帶 mcpAllowedTools 或傳 []，都會被換成當下取得的全部工具名稱（見建立工具時的連線驗證），因此不能用 [] 關閉所有工具。

• 對應到 OAuth MCP Registry 的工具：[] 會原樣保存；更新時若傳 [] 或沒帶這個欄位，允許清單也會被清空，shared 模式下就一個工具都不開放。更新這類工具時請一律帶上完整的 mcpAllowedTools。

工具清單怎麼交給模型

• 何時抓：每次組裝 Agent 的工具時都會連到你的 Server 執行 tools/list，再依允許清單過濾。

• 名稱：工具有設定 name 時，模型看到的名稱是 {name}__{你的工具名}。非英數與底線的字元會換成底線、開頭不是英文字母時補 t_，超過 64 字元則截斷並加上 6 碼雜湊尾碼。

• 說明：模型看到的描述就是你在 tools/list 回的 description，請寫清楚用途與使用時機。

• 參數：inputSchema 會轉成模型的參數定義。平台會自動處理兩種常見寫法：把陣列形式的屬性值轉成 anyOf，並把本地 $ref 內嵌展開（遞迴參照會改成接受任意值）。Schema 仍無法轉換時，只會略過該工具，其他工具照常提供。

• 抓取失敗：連不上、逾時或驗證失敗時，這個 MCP 工具在本次回覆中不會提供任何工具給模型，對話本身不會中斷。

呼叫工具：逾時、重試與錯誤

Session 與逾時

• 每次 tools/call 都會新開一個 MCP session（initialize 後再呼叫），不會跨呼叫重用 session。需要跨呼叫保存狀態時，請以 X-Conversation-Id 或你自己的驗證身分為依據。

• MCP session 的讀取逾時為 30 秒。

暫時性錯誤的自動重試

連線逾時、連線中斷或被重設、Server 未回應就斷線、session 中途關閉，以及 MCP 錯誤碼為連線關閉或 408 時，平台最多重試 3 次，間隔 1、2、4 秒（上限 8 秒）。你的 Server 回傳的錯誤結果或應用層錯誤不會重試。

只有「重送也安全」的工具才會重試，判斷順序：

1. 工具的 annotations 有 readOnlyHint: true 或 idempotentHint: true → 會重試。

2. 其中任一明確為 false → 不重試。

3. 兩者都沒宣告時，看工具名稱的第一個字是否為 get、list、read、fetch、search、find、check、query、describe、show、view、browse、lookup（camelCase、- 會先拆字）。

建議在 tools/list 為每個工具明確宣告 readOnlyHint／idempotentHint。會產生副作用的工具（下單、送出表單）請標為 false，避免斷線後被重送。

回給模型的內容

情況	模型看到的內容
呼叫成功	CallToolResult 轉成的文字（包含 content、structuredContent 與 isError 欄位）。你回 isError: true 時，模型一樣會看到這段內容。
呼叫時拋出例外（重試後仍失敗、非暫時性錯誤）	MCP 工具執行錯誤\n MCP Tool Execution Error: <錯誤內容>
結果過長	上限為模型 context window × 工具輸出比例（預設 0.8），以 token 估算。超過時保留開頭與結尾各一半，中間省略，並在最前面加上說明「結果不完整」的提示。

每次呼叫都會寫入工具執行記錄（工具、實際 MCP 工具名稱、輸入參數、輸出或錯誤、耗時、重試次數），除錯方式同 API 工具工程指南的記錄與除錯。

計費分類

每次成功呼叫計 1 次 MCP 工具用量，依工具名稱分為讀取類或寫入類：名稱第一個字符合上述讀取字首就算讀取類，否則名稱中含寫入關鍵字時算寫入類，其餘都算讀取類。組織點數不足時，這次呼叫不會送到你的 Server。

MCP Apps（互動卡片）

MaiAgent 支援 MCP Apps 擴充（SEP-1865）：工具除了回傳資料，還可以附上一份 HTML 介面，對話中就會出現一張可操作的卡片，例如圖表、表單或查詢結果清單。使用者看到的效果與限制見使用者手冊的 MCP 互動卡片（MCP Apps）；想直接動手，跳到最小可跑範例。

伺服器端：怎麼回傳 UI 資源

1. 連結 UI 資源：在 tools/list 的工具定義，或 tools/call 結果的 _meta 帶上 ui.resourceUri，值必須以 ui:// 開頭，例如 {"_meta": {"ui": {"resourceUri": "ui://orders/list"}}}。兩處都有時以呼叫結果的為準；扁平寫法 _meta["ui/resourceUri"]（@modelcontextprotocol/ext-apps 的 registerAppTool 產生的格式）也接受。工具定義的 _meta 在每次組裝工具清單時讀取。

2. 提供資源內容：工具呼叫成功後，平台在同一個 MCP session 對這個 URI 送出 resources/read，取第一筆內容的 text 當作卡片 HTML。建議 mimeType 使用 text/html;profile=mcp-app。

3. 回傳資料：卡片收到的是這次的工具結果：content 的第一段文字，以及 structuredContent（物件）。請讓卡片以 structuredContent 為資料來源；平台不會把工具輸入參數傳給卡片（ui/notifications/tool-input 的 arguments 為空物件）。

平台的 MCP client 在 initialize 時不會宣告 io.modelcontextprotocol/ui 擴充能力。請不要用 getUiCapability() 之類的判斷來決定要不要附上 _meta，否則平台永遠拿不到 UI 資源。

以下情況不會出現卡片，或改以文字顯示：

情況	結果
工具結果 isError: true	不產生卡片
沒有連結 ui:// 資源	不產生卡片，對話照常顯示工具結果
resources/read 失敗或沒有內容	卡片改顯示 content 的第一段文字

卡片 HTML 會在產生當下隨訊息保存。之後更新伺服器上的 UI，不會改變歷史訊息中已產生的卡片，請讓新版 UI 能處理舊版產生的資料。

前端：卡片怎麼呈現

• 出現位置：Agent 回覆完成後，卡片出現在該則回覆下方；同一則回覆中，來自同一來源、同一個 UI 資源的卡片只顯示最新一張。

• 沙盒：卡片在 sandbox="allow-scripts" 的 iframe 中執行（沒有 allow-same-origin），無法讀取宿主頁面的 Cookie 與儲存空間，也無法自行開新視窗。

• 內容安全政策（CSP）：預設只允許內嵌的 script 與 style，圖片、媒體與字型只接受 data:／blob:，connect-src 為 'none'（不能對外發出請求），也不能送出表單。請把 JS、CSS 與圖片都打包進同一份 HTML。

• 額外允許的來源：卡片確實需要載入外部資源時，在組織私有 MCP Registry（/api/v1/mcp/private-registry/）的 cspAllowedOrigins 列出來源。只接受 https:// 開頭、不含路徑與萬用字元的 origin，例如 https://viewer.example.com。建立或更新 MCP 工具時，網址開頭符合 Registry remoteMcpUrl 的工具會對應到該 Registry。

• 尺寸與顯示模式：卡片預設高度 220px，依卡片以 ui/notifications/size-changed 回報的 height 調整（上限 2000px），訊息流中的最大高度為 min(62vh, 620px)，超過時在卡片內捲動。卡片可以請求切換為全螢幕（fullscreen），平台會在右上角加上退出按鈕，也可按 Esc 返回，收合後維持卡片最後回報的高度；請求 pip 時以一般（inline）模式顯示。

• 串流中不顯示：Agent 回覆串流結束後才掛載卡片；同一則回覆多次更新時，平台以 ui/notifications/tool-result 原地推新結果，不重建 iframe。

卡片與宿主的握手

卡片與平台之間以 MCP Apps 的 JSON-RPC 透過 window.parent.postMessage 溝通（宿主端使用 @modelcontextprotocol/ext-apps 1.2 的 AppBridge，協定版本 2026-01-26）。順序：

1. 卡片送 ui/initialize（appInfo、appCapabilities、protocolVersion）。平台回 hostInfo、hostCapabilities（serverTools、message.text、openLinks）與 hostContext（displayMode、availableDisplayModes: ["inline", "fullscreen"]、theme: { primaryColor, mode }）。

2. 卡片送 ui/notifications/initialized。

3. 平台依序推 ui/notifications/tool-input（arguments 為空）與 ui/notifications/tool-result（完整 CallToolResult）。之後顯示模式或主題改變時推 ui/notifications/host-context-changed；卡片卸載前送 ui/resource-teardown 請求。

平台另外會在卡片 HTML 的 <head> 注入 window.__MCP_INITIAL_RENDER_DATA__（同一份工具結果），讓卡片在握手完成前就能先畫；正式資料仍以 tool-result 通知為準。

卡片可以呼叫的宿主功能

方法	平台的處理
tools/call	由平台代為呼叫，卡片無法直接連到你的伺服器或 MaiAgent 後端。只能呼叫產生這張卡片的同一個 MCP 來源、且在這段對話中已啟用並在允許清單內的工具，驗證標頭與 Agent 呼叫時相同。單次呼叫逾時 30 秒；回給卡片的結果只保留 content 的第一段文字、structuredContent 與 isError。失敗時卡片外會顯示「這個動作沒有完成，請稍後再試一次。」
ui/message	content 需為內容區塊陣列，平台取出其中的文字區塊，當作使用者訊息送進對話並先把卡片收合回 inline，由 Agent 接著回答
ui/open-link	由平台開啟新分頁，只接受 https:、http:、tel:、mailto:，網址中的帳號密碼會被移除；不允許或被瀏覽器擋下時回 { "isError": true }
ui/request-display-mode	在 inline 與 fullscreen 之間切換，回覆實際生效的模式
ui/notifications/size-changed	依 height 調整卡片高度（全螢幕時忽略）
ui/download-file、ui/update-model-context、resources/read	未支援，平台回 -32601 Method not found

適用範圍

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

• 對 Agent 掛載的 MCP 工具（Agent 模式），以及成員在 MaiGPT 授權使用的連接器都有效，MaiAgent 這一端不需要額外開關。

• 地端部署的 Web Chat 是否顯示卡片依部署設定而定，請洽 MaiAgent 窗口。

最小可跑範例

一支 Node.js（18 以上）的 MCP Server：一個查訂單狀態的工具（回傳假資料）連結 ui://orders/status 卡片，卡片能重新查詢、也能向 AI 提問。三個檔案放在同一個資料夾。

1

建立專案

mkdir order-status-mcp && cd order-status-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

2

server.mjs：工具與 UI 資源

import { createServer } from 'node:http'
import { readFileSync } from 'node:fs'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import { z } from 'zod'

const PORT = Number(process.env.PORT ?? 8787)
const CARD_URI = 'ui://orders/status'
const CARD_HTML = readFileSync(new URL('./card.html', import.meta.url), 'utf8')

// 假資料：正式環境換成查你的系統
const ORDERS = {
  A1001: { status: 'shipped', carrier: '黑貓宅急便', eta: '2026-10-06', items: ['無線滑鼠 ×1', 'USB-C 線 ×2'] },
  A1002: { status: 'processing', carrier: null, eta: '2026-10-08', items: ['機械鍵盤 ×1'] },
}

function buildServer() {
  const server = new McpServer({ name: 'order-status-demo', version: '1.0.0' })

  server.registerTool(
    'get_order_status',
    {
      description: '查詢訂單目前的出貨狀態與預計送達日',
      inputSchema: { orderId: z.string().describe('訂單編號，例如 A1001') },
      annotations: { readOnlyHint: true },
      // 連結互動卡片：平台讀 _meta.ui.resourceUri
      _meta: { ui: { resourceUri: CARD_URI } },
    },
    async ({ orderId }) => {
      const order = ORDERS[orderId]
      if (!order) {
        return { isError: true, content: [{ type: 'text', text: `找不到訂單 ${orderId}` }] }
      }
      return {
        // content 的第一段文字＝模型看到的內容，也是卡片載入失敗時的純文字備援
        content: [{ type: 'text', text: `訂單 ${orderId}：${order.status}，預計 ${order.eta} 送達` }],
        // 卡片以 structuredContent 為資料來源
        structuredContent: { orderId, ...order },
      }
    },
  )

  // 卡片 HTML：工具呼叫成功後，平台在同一個 session 對這個 URI 送 resources/read
  server.registerResource(
    'order-status-card',
    CARD_URI,
    { mimeType: 'text/html;profile=mcp-app' },
    async (uri) => ({
      contents: [{ uri: uri.href, mimeType: 'text/html;profile=mcp-app', text: CARD_HTML }],
    }),
  )

  return server
}

createServer(async (req, res) => {
  if (new URL(req.url, 'http://localhost').pathname !== '/mcp') {
    res.writeHead(404).end()
    return
  }
  // 無狀態模式：每個請求各自建立 server + transport；平台每次呼叫本來就會新開 session
  const server = buildServer()
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
  res.on('close', () => { transport.close(); server.close() })
  await server.connect(transport)
  await transport.handleRequest(req, res)
}).listen(PORT, () => console.log(`MCP server listening on http://localhost:${PORT}/mcp`))

3

card.html：單檔卡片

不引入任何套件，直接用 postMessage 走 JSON-RPC：握手、接收 tool-result、回報高度、tools/call 重新查詢、ui/message 向 AI 提問。JS、CSS 都寫在同一個檔案裡（沙盒 CSP 不允許載入外部資源）。

<!doctype html>
<html lang="zh-Hant">
<head>
<meta charset="utf-8">
<style>
  body { margin: 0; padding: 16px; font: 14px/1.6 system-ui, sans-serif; color: #1f2937; }
  h4 { margin: 0 0 8px; font-size: 16px; }
  .status { display: inline-block; padding: 2px 8px; border-radius: 999px; background: #e0f2fe; color: #075985; }
  table { border-collapse: collapse; margin: 8px 0; width: 100%; }
  td { padding: 4px 0; border-bottom: 1px solid #e5e7eb; }
  button { margin: 8px 8px 0 0; padding: 8px 14px; border: 0; border-radius: 6px; background: #2563eb; color: #fff; cursor: pointer; }
  button.secondary { background: #6b7280; }
  #hint { color: #6b7280; }
</style>
</head>
<body>
  <div id="view"><p id="hint">載入中…</p></div>
  <button id="refresh" hidden>重新查詢</button>
  <button id="ask" class="secondary" hidden>問 AI 這筆訂單</button>

<script>
  // ---- 與宿主（MaiAgent）的 JSON-RPC 往返：全部走 window.parent.postMessage ----
  var pending = {}
  var nextId = 1
  var currentOrder = null

  function request(method, params) {
    var id = nextId++
    return new Promise(function (resolve, reject) {
      pending[id] = { resolve: resolve, reject: reject }
      window.parent.postMessage({ jsonrpc: '2.0', id: id, method: method, params: params }, '*')
    })
  }
  function notify(method, params) {
    window.parent.postMessage({ jsonrpc: '2.0', method: method, params: params || {} }, '*')
  }

  window.addEventListener('message', function (event) {
    var msg = event.data
    if (!msg || msg.jsonrpc !== '2.0') return
    // 1) 我方請求的回覆
    if (msg.id !== undefined && !msg.method) {
      var p = pending[msg.id]
      if (!p) return
      delete pending[msg.id]
      msg.error ? p.reject(msg.error) : p.resolve(msg.result)
      return
    }
    // 2) 宿主推來的通知：握手完成後會先收到 tool-input，再收到 tool-result
    if (msg.method === 'ui/notifications/tool-result') render(msg.params)
    // 3) 宿主請求卡片收尾：回一個空結果即可
    if (msg.method === 'ui/resource-teardown' && msg.id !== undefined) {
      window.parent.postMessage({ jsonrpc: '2.0', id: msg.id, result: {} }, '*')
    }
  })

  // ---- 畫面 ----
  function render(result) {
    var data = result && result.structuredContent
    var view = document.getElementById('view')
    if (!data || result.isError) {
      var text = result && result.content && result.content[0] ? result.content[0].text : '沒有資料'
      view.innerHTML = '<p id="hint"></p>'
      view.firstChild.textContent = text
    } else {
      currentOrder = data.orderId
      var rows = (data.items || []).map(function (i) { return '<tr><td>' + escapeHtml(i) + '</td></tr>' }).join('')
      view.innerHTML =
        '<h4>訂單 ' + escapeHtml(data.orderId) + ' <span class="status">' + escapeHtml(data.status) + '</span></h4>' +
        '<div>預計送達：' + escapeHtml(data.eta) + (data.carrier ? '（' + escapeHtml(data.carrier) + '）' : '') + '</div>' +
        '<table>' + rows + '</table>'
      document.getElementById('refresh').hidden = false
      document.getElementById('ask').hidden = false
    }
    // 回報高度，宿主會依此調整卡片高度
    notify('ui/notifications/size-changed', { height: document.body.scrollHeight })
  }
  function escapeHtml(s) {
    return String(s).replace(/[&<>"]/g, function (c) { return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c] })
  }

  // 卡片內的動作：由宿主代為呼叫同一個 MCP server 的工具
  document.getElementById('refresh').addEventListener('click', function () {
    request('tools/call', { name: 'get_order_status', arguments: { orderId: currentOrder } })
      .then(render)
      .catch(function (err) { console.error('tools/call failed', err) })
  })
  // 卡片內提問：文字會成為一則使用者訊息送進對話，由 Agent 接著回答
  document.getElementById('ask').addEventListener('click', function () {
    request('ui/message', { role: 'user', content: [{ type: 'text', text: '訂單 ' + currentOrder + ' 什麼時候會到？' }] })
  })

  // ---- 握手：ui/initialize → ui/notifications/initialized，之後宿主才會推 tool-result ----
  request('ui/initialize', {
    appInfo: { name: 'order-status-card', version: '1.0.0' },
    appCapabilities: {},
    protocolVersion: '2026-01-26',
  }).then(function () {
    notify('ui/notifications/initialized')
  })
</script>
</body>
</html>

4

啟動並驗證

node server.mjs
# MCP server listening on http://localhost:8787/mcp

另開一個終端機，依平台的順序打三個請求（無狀態模式不需要 session 標頭）：

MCP=http://localhost:8787/mcp
H='-H Content-Type:application/json -H Accept:application/json,text/event-stream'

# 1) tools/list：確認工具帶 _meta.ui.resourceUri
curl -s $MCP $H -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# {"result":{"tools":[{"name":"get_order_status", ... ,"_meta":{"ui":{"resourceUri":"ui://orders/status"}}}]}, ...}

# 2) tools/call：確認有 content 文字與 structuredContent
curl -s $MCP $H -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_order_status","arguments":{"orderId":"A1001"}}}'
# {"result":{"content":[{"type":"text","text":"訂單 A1001：shipped，預計 2026-10-06 送達"}],"structuredContent":{"orderId":"A1001","status":"shipped", ...}}, ...}

# 3) resources/read：確認回傳整份 HTML
curl -s $MCP $H -d '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"ui://orders/status"}}'
# {"result":{"contents":[{"uri":"ui://orders/status","mimeType":"text/html;profile=mcp-app","text":"<!doctype html>..."}]}, ...}

三個都回對了，平台這一端就能產生卡片。

接進 MaiAgent 的步驟

1. 讓 Server 從公網以 https:// 存取（本機測試可用 cloudflared tunnel --url http://localhost:8787 或 ngrok http 8787 之類的工具取得暫時網址），MCP 端點為 https://<你的網域>/mcp。

2. 依使用者手冊的建立 MCP 工具在後台新增 MCP 工具，網址填上一步的端點；本範例不需要標頭。「允許的工具」重新取得後應列出 get_order_status。

3. 把工具配置給回答模式為 Agent 模式的 Agent，在 Web Chat 或 MaiGPT 問「A1001 這筆訂單到哪了？」。Agent 回覆完成後，卡片會出現在回覆下方；點 重新查詢 走 tools/call、點 問 AI 這筆訂單 走 ui/message。使用者端的行為見 MCP 互動卡片（MCP Apps）。

常見錯誤

現象	原因
Agent 有呼叫工具，但沒出卡片	tools/list 的工具定義與 tools/call 結果都沒有 _meta.ui.resourceUri（或值不是 ui:// 開頭）、工具回了 isError: true、或是在 LINE 等不顯示卡片的通路
卡片位置只顯示純文字	resources/read 失敗或回空內容，平台改用 content 第一段文字；用上面第 3 個 curl 確認
卡片一直停在「載入中…」	卡片沒有完成握手（ui/initialize 的 params 缺 appInfo／appCapabilities／protocolVersion，或沒送 ui/notifications/initialized），平台不會推 tool-result；也可能是卡片 HTML 載入了外部 JS 被 CSP 擋下
卡片空白	HTML 依賴外部 CSS／JS／圖片而被沙盒 CSP 擋下，請打包進同一份 HTML，或在 Registry 設定 cspAllowedOrigins
卡片顯示「這個動作沒有完成，請稍後再試一次。」	卡片的 tools/call 被平台拒絕或失敗：工具名稱不在該 MCP 工具的允許清單、工具已從 Agent 移除、授權失效、Server 回錯或超過 30 秒未回應
卡片的「問 AI」沒反應	ui/message 的 content 不是陣列、或沒有 type: "text" 的區塊

上線前檢查清單

• 端點是 https://、可從公網存取，使用 Streamable HTTP；只支援 SSE 時 URL 以 /sse 結尾。

• 只帶固定標頭時 tools/list 也能正常回應。

• 每個工具的 description 寫清楚用途，inputSchema 是合法的 JSON Schema。

• 為每個工具宣告 readOnlyHint／idempotentHint。

• 不依賴跨呼叫的 MCP session；需要狀態時改用 X-Conversation-Id 或使用者身分。

• 使用者層級權限：規劃好聯絡人 MCP 憑證的寫入時機（登入時同步、登出時刪除）。

• 使用 OAuth：支援 RFC 9728 資源中繼資料、RFC 8414 授權伺服器中繼資料、PKCE（S256）與 resource 參數；不支援動態註冊時，兩個 Callback URL 都已登記。

• Server 新增工具後，回到工具設定重新取得清單。

• 提供互動卡片時：以 _meta.ui.resourceUri 連結 ui:// 資源、resources/read 回傳完整 HTML，卡片以 structuredContent 為資料來源、不對外發出請求（需要時在 Registry 設定 cspAllowedOrigins）。