代理商務（MCP）

商店前台與帳戶 MCP 伺服器

最後更新：2026年10月3日

STOAR 內建一套 Model Context Protocol 介面，讓 AI 購物代理——ChatGPT、Claude 以及任何其他 MCP 用戶端——都能探索您的商店、搜尋商品目錄、依您發布的政策回答問題、建立購物車、計算真實的到貨總額，並把安全連結交給顧客，讓他們在瀏覽器中完成結帳。在顧客明確同意下，代理之後也能查詢其訂單。

它與商店前台和 REST API 共用同一套核心，只是以另一個協定轉接器的形式對外提供。幕後不會另造一套邏輯：代理建立的購物車就是一般的訪客購物車，而價格來自結帳時所用的同一套計算器——因此代理報出的數字，正是最終收取的金額。

兩個伺服器 #

伺服器	路徑	驗證	範圍
商店前台	`/mcp`	無	商店資訊、商品目錄、政策、購物車、運送報價、訪客訂單查詢
帳戶	`/mcp/account`	顧客權杖	登入顧客自己的訂單紀錄

這是完整的買方端層級。商家與管理操作——編輯商品、退款、調整庫存——刻意不 對代理開放。

選擇性啟用，且預設關閉 #

代理商務採選擇性啟用。兩個伺服器在您啟用前都維持關閉，而未啟用的商店會回應 404——它甚至不會被發現是一台 MCP 主機。請在 Manager → Agent Access（MCP）中啟用，您也可在此控制：

兩個伺服器各自是否開啟；
代理是否必須先表明身分才能動作；
購物車上限（每行最大數量、行數上限、購物車金額上限）；
交接結帳連結的有效期限；
請求速率與結果筆數限制。

變更會在下一個請求生效——無需部署。兩個伺服器都無法建立訂單、收款或變更既有訂單。 金流只會在顧客於自己的瀏覽器中完成結帳後才發生。

快速開始 #

伺服器依請求網域按商店掛載，與 REST API 完全相同：

https://{您的商店網域}/mcp

將任何 MCP 用戶端指向它，或直接列出工具：

curl -s https://app.stoar.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

最精簡的購物流程只需五個呼叫：先取得一次商店條款、找到商品、讀取其款式、建立購物車，然後計算到貨總額並把 cart.continue_url 交給顧客。

工具 #

商品目錄

工具	功能
`get_store_info`	商店自身的條款——寄送地區、收款與顯示的幣別、啟用的付款方式、退貨期限、免運門檻與支援語言。呼叫一次並重複使用。
`search_catalog`	自由文字與條件篩選搜尋，含價格、分類、庫存與排序篩選。
`get_product`	單一商品的完整細節，含款式矩陣——加入任何品項前都需先取得。
`check_availability`	最多 20 個品項的批次庫存重查，並為任何缺貨品項提供有庫存的替代品。

政策

工具	功能
`search_shop_policies_and_faqs`	從您的運送、退貨、隱私、條款、聯絡與 FAQ 內容中取出排序後的段落——每段皆附可引用的網址，並以代理詢問的語言作答。

購物車

所有購物車工具都以 create_cart 回傳的 cart_id 權杖來定址。

工具	語意
`create_cart`	建立新購物車，可選擇預先放入品項。
`get_cart`	取得完整的目前狀態。
`add_cart_items`	累加——數量會加到既有的行上。
`update_cart_items`	每行的絕對數量；`0` 代表移除。
`remove_cart_items`	移除指定的行。
`cancel_cart`	清空並使購物車失效。
`estimate_shipping`	依各可用運送方式回傳到貨總額，最便宜者優先，輸入國家（必要時加郵遞區號）。

購物車工具採精準操作，而非整車覆寫：每個呼叫只點名自己要動的部分，因此一個搞混的代理可能無法完成動作，卻不會默默刪掉它忘了重送的品項。每次異動都回傳完整購物車。每次異動都具冪等性——重送同一請求會回傳原本的結果，而不會重複套用。

訂單

工具	位置	說明
`get_order_status`	`/mcp`（訪客）	需要訂單編號以及確認信中的查詢權杖。
`list_orders` / `get_order`	`/mcp/account`	登入顧客自己的訂單，唯讀。

交接 #

代理會建立一個它永遠無法付款的購物車。cart.continue_url 就是讓這個購物車化為真實交易的途徑：顧客在瀏覽器中開啟它，購物車載入其工作階段，隨後進入正常結帳。該連結經過簽章、有時效、限定單一商店，且永遠只承載訪客購物車——絕不承載登入顧客的購物車或其已儲存地址。

安全模型 #

/mcp 刻意不需驗證。 它所公開的一切，要嘛本就公開（商品目錄、政策），要嘛以無法猜測的權杖定址（購物車，或憑其以電子郵件寄送之查詢權杖的單筆訂單）。沒有顧客自己的憑證，便無法存取任何顧客資料、訂單紀錄、付款或地址。
/mcp/account 需要顧客自行建立的權杖，範圍限於單一唯讀能力。它不是管理者憑證，也無法驅動任何其他 API。
訪客訂單查詢以權杖把關，而非電子郵件 + 訂單編號。 訂單編號是連續的，因此若把電子郵件式查核開放給機器，將可逐一列舉他人的購買紀錄。每筆訂單專屬的權杖已在確認信中——不會另外發出，也不會另外外洩。
對訪客隱藏的價格仍維持隱藏。 在對未登入訪客隱藏價格的 B2B 商店，代理看到同樣的遮蔽，且購物車功能會停用，而不會產生一個價值不明的購物車。
租戶由請求網域決定，無法被任何參數覆寫，因此一家商店的代理絕不會存取到另一家的商品目錄或購物車。

衡量成效 #

當代理存取啟用時，儀表板會顯示近 30 天的代理購物車、代理訂單、代理營收（已扣除退款），以及依訂單數排名的首要代理——讓您回答每個人對代理商務的第一個問題： 它到底有沒有在賣東西？

與 Shopify 的比較 #

Shopify 已停用其 Storefront MCP，改採 Universal Commerce Protocol，而其代理結帳屬於僅限合作夥伴的預覽。STOAR 今日即提供完整的買方端介面，並加入多項 UCP 沒有對應項目的能力：

get_store_info——否則代理只能猜測寄送地區、付款方式與退貨期限。
estimate_shipping——出自真實結帳計算器的到貨總額，而非僅是小計。
訪客訂單查詢——Shopify 的僅限登入者，因此訪客訂單（真實流量的一大部分）一無所獲。
精準的購物車修改，而非會默默刪掉代理忘了重送之任何行的整車覆寫式 update_cart。
每次異動都具冪等性，而不只是取消。
有庫存的替代品，當某品項缺貨時提供。

目前的限制 #

MCP 無法處理退貨、取消或地址變更。 這些都是不可逆的動作，應置於傳輸尚無法保證的明確人工確認之後；代理會將顧客導向帳戶頁面。
組合商品與訂閱可讀取但無法透過代理購買——兩者都會被標記，讓代理把顧客導向商品頁，而不是以錯誤價格加入錯誤的東西。
訂單狀態由商家自行填寫——每筆訂單一組追蹤號碼，無即時物流串接，且狀態備註會被標記為可能已過時。
政策內容沿用商店前台的翻譯頁面，因此修改需要部署，而非在 Manager 中編輯。