MCP 技術文件

給開發者／技術使用者看的完整參考。一般使用者不需要看這頁，直接到連接 AI 助理介紹頁複製指令丟給你的 AI 助理即可。

連線資訊快速開始可用工具使用限制相關連結

連線資訊

端點 (Endpoint)	`https://mcp.oneheartesim.com/`
傳輸方式	Streamable HTTP（MCP 官方標準傳輸方式）
身分驗證	公開、無需 API Key
官方 Registry 名稱	`com.oneheartesim.mcp/esim`

直接用瀏覽器打開這個網址會看到一段 JSON 錯誤，這是正常的，不是故障。 這個端點只接受正確的 MCP JSON-RPC 協定請求（含 Mcp-Session-Id 等標頭）；瀏覽器單純瀏覽是陽春的 GET 請求，不符合協定要求，伺服器如實回報格式錯誤。真正的 MCP 用戶端（Claude 等 AI 助理）連線時會走完整的協定交握，不會遇到這個訊息。

快速開始

方法一：直接跟你的 AI 助理說

把下面這段話丟給支援 MCP 的 AI 助理（例如 Claude），大部分助理能自己完成連線設定：

請幫我連接這個遠端 MCP 伺服器：https://mcp.oneheartesim.com/。連線後，請確認你是否已經可以使用「一心漫遊 (ONE HEART eSIM)」的查價與下單工具。

方法二：手動加到 MCP 用戶端設定

在你的 AI 助理／MCP 用戶端的連接器設定裡，新增一個遠端伺服器，網址填 https://mcp.oneheartesim.com/，傳輸方式選 Streamable HTTP。實際設定畫面/設定檔格式依你使用的用戶端而異，請參考該用戶端自己的 MCP 連接器說明文件。

可用工具

共 5 個工具，前 4 個唯讀查詢，最後 1 個會建立真實訂單

list_esim_countries 唯讀

列出目前販售方案覆蓋的所有國家/地區（英文與中文名稱對照，含各國方案數量）。

沒有參數

search_esim_plans 唯讀

依國家、方案類型、關鍵字搜尋商品清單，一次回傳多筆結果供比較。

參數	型別	說明
`country`	string？	國家名稱，英文或中文皆可，模糊比對
`planType`	enum？	總量型 / 每日定量型，留空不限
`keyword`	string？	自由關鍵字，比對商品名稱/描述/規格
`limit`	int？	最多回傳筆數，預設 20，上限 50

get_esim_plan_detail 唯讀

取得單一方案完整詳情（安裝/啟用說明、各規格庫存、購買連結）。

productId string（必填）方案的 GUID，需從其他查詢工具的結果取得

recommend_esim_plan 唯讀

依旅遊天數與用量習慣，評分推薦最合適的 1-3 個方案並附購買連結。

參數	型別	說明
`country`	string（必填）	目的地國家，英文或中文皆可
`days`	int（必填）	預計使用天數
`usageLevel`	enum？	light / medium / heavy，預設 medium

create_esim_order 會寫入真實訂單

建立真實訂單並取得真實付款連結（LinePay 或 ECPay 綠界擇一）。這是真的會產生訂單、串真實金流的動作。

參數	型別	說明
`productId`	string（必填）	方案 GUID，需從查詢工具取得
`spec`	string（必填）	方案規格，須與查詢結果的 spec 完全一致
`quantity`	int（必填）	購買數量
`email`	string（必填）	訂單憑證與 eSIM 寄送地址
`userName`	string（必填）	訂單聯絡人稱呼/姓名
`paymentMethod`	enum？	LinePay / ECPay，預設 LinePay
`phone`	string？	選填

使用限制與已知行為

建單目前非冪等（idempotent）。若 AI 助理因逾時等原因重複呼叫 create_esim_order，可能建立多筆重複的「待繳費」訂單（金額不會重複收款，因為仍需使用者各自完成付款）。
下單只需 Email 與稱呼即可完成，手機號碼為選填；訂單建立後仍須自行完成付款，付款前不會出貨。
目前不支援查詢會員資料或歷史訂單記錄；每次查詢都是即時資料，不做快取。
所有查詢工具皆公開、無需金鑰；下單工具亦無需金鑰，但會產生真實訂單，請勿在非預期情境下呼叫。