將 AI 代理連接到 ShipStation：僅文件 MCP 伺服器無法解決的問題

關鍵要點

• 第一方 MCP 僅用於文件 — ShipStation 的官方 MCP 伺服器位於 docs.shipstation.com/mcp，搜尋 API 參考資料。它幫助代理了解端點如何運作。無法讀取訂單、建立標籤、更新庫存或作廢出貨。與 BigCommerce 相同的僅文件模式。
• V1 每分鐘 40 次請求，V2 為 200 次 — ShipStation V1 API（Basic Auth，即將棄用）限制為每個金鑰每分鐘 40 次呼叫。目前 V2 API（前身為 ShipEngine）允許 200 次。一個代理對 V1 發起 30 次並行工具呼叫會在幾秒內耗盡配額視窗。
• 內建 NetSuite 連接器無法映射自訂欄位 — 每月 200 美元的 ShipStation-NetSuite 整合支援三種工作流程變體，但不支援自訂欄位映射。折扣、禮品留言和特殊處理說明無法同步。第三方連接器（Nova Module 每月 400 美元、Celigo）以付費方式填補缺口。
• 透過 StackOne 提供 45 個託管 MCP 操作，但沒有 B2B 語意層 — StackOne 的 ShipStation MCP 伺服器涵蓋承運商、訂單、產品、倉庫、店鋪、標籤、履約和標記。這是一個通用封裝。沒有自訂欄位解析、沒有帶語意映射的 ERP 回寫、沒有可審查的寫入計畫。
• Anthropic 2026 年調查將整合列為第一採用障礙，佔 46% — 對於使用 NetSuite 或 Brightpearl 作為 ERP 的 ShipStation 商戶，障礙不在於連接。而在於運送資料與財務記錄之間的語意層。

問題：文件不是營運

Anthropic 2026 年 AI 代理現狀報告 調查了 500 多位技術領導者，他們在 Novo Nordisk、Doctolib、L'Oréal 和 Shopify 有實際實施經驗。整合是第一採用障礙，佔 46%。對於 ShipStation 商戶，這一障礙有具體形態：供應商發布了 MCP 伺服器，教代理了解 API，但不讓代理使用它。

逐連接器系列已映射了五個供應商。NetSuite 發布了帶有 MCP 端點的 AI Connector Service — 自訂模組填補語意層缺口（哪些 GL 帳戶是「收入」）。Shopify 發布了 Storefront MCP 伺服器並與 Google 共同開發了 Universal Commerce Protocol — 自訂模組填補 B2B 缺口（客戶分層定價、批量 RFQ 報價）。HubSpot 發布了帶有 12 個工具的 Remote MCP Server — 自訂模組填補六個能力缺口（自訂物件、可審查寫入、無頭認證）。BigCommerce 與 Stripe 合作開發 Agentic Commerce Suite — 自訂模組填補 B2B Price List 和 Customer Group 缺口。Brightpearl 什麼也沒發布 — 自訂模組就是整合本身。

ShipStation 是第六個案例，模式是文件路徑。ShipStation 是一個多承運商運送平台，中型市場的 B2B 和電商商戶用它來比較承運商費率、列印標籤和追蹤 UPS、FedEx、USPS 和 DHL 的出貨。它有一個 V2 API（前身為 ShipEngine），涵蓋費率比價、出貨、標籤、批次、退件標籤、清單、取貨、產品、庫存、倉庫和位置。它發布了一個官方 MCP 伺服器 — 但該伺服器提供對 API 文件和參考資料的存取，而非店鋪資料。連接到它的代理可以了解建立出貨端點如何運作。它無法建立出貨。

本文映射了現有的三種代理整合路徑、決定速率限制和壽命的 V1/V2 API 分割、NetSuite 連接器的自訂欄位缺口，以及使 ShipStation 面向生產 B2B 工作流程的代理就緒的自訂 MCP 模組模式。

三種代理整合路徑

ShipStation 代理整合格局分為三層：文件（第一方）、託管封裝（第三方）和自訂模組（直接 V2 API）。

路徑 1：僅文件 MCP（第一方）

ShipStation 的官方 MCP 伺服器 位於 docs.shipstation.com/mcp，連接 Claude Code、Cursor 和 VS Code。伺服器自身的文件明確說明了限制：「此 MCP 伺服器提供對 API 文件和參考資料的存取。它使 AI 助手能夠探索 ShipStation API 規範、解釋端點並指導您的整合工作。對於直接 API 操作，請使用您的憑證呼叫 ShipStation API。」

連接到此伺服器的代理可以回答「Label 資源的 schema 是什麼？」或「顯示所有可用的 ShipStation 端點」等問題。它無法建立標籤、列出訂單或檢查追蹤狀態。文件 MCP 是開發者生產力工具，不是營運工具。它幫助人類開發者更快建構整合。它不讓代理營運運送平台。

這與 BigCommerce 的模式相同，BigCommerce 在 docs.bigcommerce.com/_mcp/server 發布了一個僅文件 MCP 用於開發者文件搜尋。兩個供應商都認識到 MCP 是 AI 工具存取的標準並發布了文件介面。兩者都沒有發布用於店鋪營運的事務性 MCP 伺服器。區別在於 BigCommerce 與 Stripe 合作開發 Agentic Commerce Suite 來覆蓋消費者代理路徑。ShipStation 沒有在可比的事務性代理介面上合作。

路徑 2：託管 MCP（StackOne、Zapier、社群）

三個第三方託管 MCP 伺服器封裝了 ShipStation API 以供代理存取：

StackOne 發布了 45 個預建構操作，涵蓋承運商（列表、取得）、客戶（列表、取得）、訂單（列表、取得、刪除、建立或更新、標記管理、保留/恢復、分配使用者、標記為已出貨）、產品（列表、取得、更新）、店鋪（列表、取得、更新、重新整理、停用、重新啟用）、倉庫（完整 CRUD）、標籤（建立、作廢）、費率（取得運送費率）、履約（列表）和帳戶管理（註冊、列出使用者、列出標記、承運商包裹和服務）。StackOne 提供託管的按使用者 OAuth 認證、提示注入防禦（88.7% 準確率，僅 CPU）和一個減少上下文膨脹的工具發現層。這些操作映射到 ShipStation 的 V1 API 介面。

Zapier MCP 透過 Zapier 的 MCP 用戶端暴露 ShipStation 操作。操作包括建立訂單、管理出貨和觸發 webhooks。Zapier 集中處理認證 — 不暴露憑證。限制在於任務消耗：每次 MCP 呼叫計為一個 Zapier 任務，而 ShipStation V1 API 已經以每分鐘 40 次請求運行。一個進行順序呼叫的代理會快速耗盡任務配額。

社群 MCP 伺服器（mattcoatsworth，MIT 授權，3 個 GitHub 星標，最後提交 2025 年 4 月）用 Basic Auth（API Key + Secret）封裝 V1 API。涵蓋訂單、出貨、承運商、倉庫、產品、客戶、店鋪、webhooks 和履約。工具列表很全面 — list_orders、get_order、create_order、mark_order_as_shipped、create_label、void_label、list_carriers、list_warehouses、subscribe_to_webhook。但該伺服器自 2025 年 4 月以來未更新，面向即將棄用的 V1 API，沒有託管認證、沒有速率限制執行，也沒有稽核日誌。

託管 MCP 伺服器解決了連接問題：代理可以透過型別化工具介面讀取和寫入 ShipStation 資料。它們沒有解決語意層問題。StackOne 的 45 個操作是圍繞 ShipStation API 的通用封裝。它們都不編碼業務含義 — 哪些訂單自訂欄位映射到哪些 NetSuite 自訂欄位、哪些運送成本應過帳到哪個 GL 帳戶、哪個倉庫名稱必須逐字元匹配 NetSuite 的 Location 欄位。託管伺服器也不執行每工具速率限制。一個對 V1 API 的 40 請求/分鐘視窗發起 30 次並行呼叫的代理會幾秒內耗盡限制，而託管伺服器不會阻止它。

路徑 3：自訂 MCP 模組（V2 API）

B2B ShipStation 整合的生產路徑是針對 V2 API 的自訂 MCP 模組。這是逐連接器系列對每個供應商得出的相同結論：第一方或託管伺服器解決連接問題，自訂模組解決語意層問題。對於 ShipStation，自訂模組填補的具體缺口是：

1. 自訂欄位映射到 NetSuite — 內建 NetSuite 連接器支援三種欄位映射變體，無法映射自訂欄位 如折扣、禮品留言或特殊處理說明。一個自訂 MCP 模組可以讀取 ShipStation 訂單自訂欄位，並寫入到 NetSuite Item Fulfillment 記錄上匹配的自訂欄位，填補 Nova Module 收取每月 400 美元來彌補的缺口。

2. V2 API 定向 — V2 API 以每分鐘 200 次請求運行（V1 限制的 5 倍），並包含 V1 API 缺乏的能力：批次標籤、退件標籤、多包裹標籤、清單、取貨和庫存管理。面向 V2 的自訂模組避免了 V1 棄用時間表並獲得了更高的速率上限。

3. 每工具速率限制執行 — V2 API 的 200 請求/分鐘在所有請求間共享。一個自訂模組可以執行每工具節流，確保進行 20 次承運商查詢的費率比價代理不會耗盡標籤建立代理的視窗。429 回應上的 Retry-After 頭為退避邏輯提供訊號。

4. 可審查的寫入計畫 — 託管 MCP 伺服器立即執行。create_label、mark_order_as_shipped 和 void_label 是產生實際成本的不可逆操作（平台使用者無沙箱）。一個自訂模組可以對寫入操作實施草稿-審查-批准工作流程，在標籤建立或訂單刪除之前設定人機協作檢查點。

5. 帶語意映射的 ERP 回寫 — 當 ShipStation 建立標籤並返回追蹤號時，內建 NetSuite 連接器將追蹤號、承運商代碼和運送成本過帳回 NetSuite。但連接器無法將實際運送成本映射到正確的 GL 帳戶，因為它不知道哪個 GL 帳戶代表該子公司的運費。一個自訂模組將該映射編碼為型別化工具，以正確的 GL 編碼過帳履約記錄。

V1/V2 API 分割

ShipStation 並行運行兩個 API 版本，這一分割對代理整合很重要，因為它決定了速率限制、認證和壽命。

V1 API（舊版）： 使用 Basic Authentication（Base64 編碼的 API Key:API Secret）。速率限制：每個 API 金鑰/金鑰集每分鐘 40 次請求。超過時回傳 HTTP 429 回應和 X-Rate-Limit-Remaining 頭。V1 API 已運行十多年，將在未來日期棄用。社群 MCP 伺服器（mattcoatsworth）和 StackOne 託管 MCP 都面向 V1。內建 NetSuite 連接器使用 V1 時代的整合模式。

V2 API（目前，前身為 ShipEngine）： 使用 API-Key 頭認證。速率限制：預設每分鐘 200 次請求，可透過支援請求更高。HTTP 429 回應帶 Retry-After 頭（等待秒數）。V2 增加了批次標籤、退件標籤、多包裹標籤、清單、取貨和庫存管理 — V1 缺乏的能力。一次僅一個 V2 金鑰活躍。需要 HTTPS 和 TLS 1.1+。

沙箱缺口： ShipStation 平台使用者（V1/V2 API）沒有沙箱環境。所有 API 操作在生產環境中進行並可能產生實際成本 — 包括標籤建立，它產生實際承運商費用。ShipEngine 沙箱（帶 TEST_ 前綴的金鑰）僅適用於 ShipStation API（前身為 ShipEngine）使用者，不適用於 ShipStation 平台使用者。這意味著對 V2 API 測試標籤建立的代理以實際成本生成真實標籤。一個自訂模組應實施謹慎的測試實踐：測試標籤使用低成本運送選項，透過 void-label 端點立即作廢，開發期間使用小批量。

V1 和 V2 之間的速率限制缺口對代理工作負載來說是營運上最顯著的差異。一個對 10 個出貨在 5 個承運商間進行費率比價的代理在突發中發起 50 次 API 呼叫。對 V1 的 40 請求/分鐘限制，該突發在完成前就超出了視窗。對 V2 的 200 請求/分鐘，它有餘量。對於批次操作 — V2 API 支援批次標籤建立，在單個請求中處理數百個標籤 — V2 速率上限是必需的。

NetSuite 連接器自訂欄位缺口

ShipStation 的內建 NetSuite 整合是 ShipStation 商戶最常見的 ERP 連接。它在 30 天試用後每月花費 200 美元，使用 Token-Based Authentication (TBA) — 與 NetSuite MCP 模組文章識別為無頭 NetSuite 營運生產認證標準相同的 OAuth 1.0a with HMAC-SHA256 模式。

連接器提供三種工作流程選項：

• Sales Order — ShipStation 處理揀貨、打包和出貨。NetSuite「Pending Fulfillment」訂單自動匯出。
• Pick Flow — NetSuite 管理揀貨。僅「Picked」Item Fulfillment Records 匯出到 ShipStation。
• Pack Flow — NetSuite 管理揀貨和打包。僅「Packed」IFRs 匯出用於標籤建立。

連接器每 3-10 分鐘輪詢 NetSuite，並在標籤建立後 5-10 分鐘內將履約資料（追蹤號、承運商、運送成本、出貨日期）過帳回。雙向同步消除了手動資料錄入 — Anchor Group 報告 企業消除了每天 4-5 小時的手動追蹤更新。

缺口是自訂欄位映射。連接器僅支援三種欄位映射變體，並明確指出：「如果您需要進一步客製化，我們建議使用我們的 Custom Store Development Guide。」自訂欄位 — 折扣、禮品留言、特殊處理說明、客戶特定運送偏好 — 不同步。位置名稱必須在系統間逐字元匹配，否則標籤無法生成。SKU 必須精確匹配，否則項目匯入為無法識別。

第三方連接器以付費方式填補缺口。Nova Module 每月收費 400 美元（按年計費）用於自訂欄位映射。Celigo 提供具有自訂定價的 iPaaS 級整合。對於每天處理 200 個訂單、每個訂單 15 個自訂欄位的商戶，手動變通方法（從 ShipStation 複製貼上自訂欄位值到 NetSuite）消耗了連接器本應消除的相同時間。

一個自訂 MCP 模組透過 V2 API 讀取 ShipStation 訂單自訂欄位，並透過 NetSuite AI Connector 或直接 SuiteTalk REST API 寫入匹配的 NetSuite 自訂欄位來填補這一缺口。該模組將欄位映射編碼為型別化工具：map_shipstation_custom_fields_to_netsuite(order_id, fulfillment_id) — 映射表作為配置，而非硬編碼邏輯。這與 NetSuite MCP 模組文章描述的語意層缺口模式相同（哪些 GL 帳戶是「收入」），應用於運送平台到 ERP 的欄位映射問題。

舊版 NetSuite 整合將於2026 年 6 月 30 日下線，被 NetSuite Beta 整合取代。下線增加了緊迫性：舊版連接器上的商戶需要遷移，遷移是評估自訂 MCP 模組是否比替換連接器提供更好自訂欄位覆蓋的機會。

自訂 ShipStation MCP 模組編碼的內容

遵循 MCP 模組程式碼標準，一個自訂 ShipStation MCP 模組編碼了僅文件伺服器和託管封裝不具備的五個方面：

1. V2 端點的型別化模式 — 每個 V2 API 端點獲得一個 JSON Schema 輸入定義，包含必填欄位、選填欄位和驗證約束。create_label 工具指定 shipment_id、carrier_id、package_type 和 weight 為必填；label_format、test_label 和 return_label 為選填。代理無法用缺失的必填欄位呼叫工具。

2. 速率限制感知執行 — 模組執行每工具並發限制和低於 V2 API 200 請求/分鐘的全域速率上限。每次工具呼叫記錄其時間戳記；模組拒絕或排隊會超出預算的呼叫。429 回應中的 Retry-After 頭以指數延遲回饋退避邏輯。

3. 自訂欄位映射表 — 模組載入一個配置，將 ShipStation 自訂欄位名稱映射到 NetSuite 自訂欄位內部 ID。當代理呼叫 sync_fulfillment_to_netsuite(order_id) 時，模組讀取 ShipStation 訂單自訂欄位，透過映射表轉換它們，並以正確的自訂欄位值寫入 NetSuite Item Fulfillment。

4. 可審查的寫入計畫 — 對於不可逆操作（標籤建立、訂單刪除、標籤作廢），模組在執行前回傳草稿計畫。代理將計畫呈現給人類操作員審批。批准後，模組執行操作並記錄稽核追蹤 — 誰批准、何時、變更了什麼、成本是多少。

5. 運送成本的 GL 編碼 — 將履約資料過帳回 NetSuite 時，模組應用 GL 編碼配置：哪個帳戶代表該子公司的運費支出、哪個部門適用於此位置、哪個類別代碼映射到此運送方式。內建連接器過帳原始運送成本；自訂模組以正確的 GL 編碼過帳成本，使財務團隊的利潤分析無需手動重分類即準確。

相關閱讀

• 將 AI 代理連接到 Brightpearl：當沒有第一方 MCP 伺服器時 — 系列的第五個連接器，自訂模組是整合本身，不是缺口填補者。ShipStation 和 Brightpearl 共享 Shopify 生態系統 — Brightpearl 是 ERP，ShipStation 是運送層。
• MCP 模組程式碼標準 — 使自訂模組在所有連接器中生產就緒的結構模式，包括速率限制執行和可審查寫入計畫。
• 將 AI 代理連接到 NetSuite with MCP：模組模式 — ERP 側的連接器。ShipStation 的自訂欄位缺口是 NetSuite 映射問題；本文涵蓋 TBA 認證和自訂欄位解析模式。

請求範圍明確的建構

一個使用 NetSuite、BigCommerce 和 ShipStation 的經銷商每天處理 200 個訂單。每個訂單攜帶 12 個自訂欄位 — 禮品留言、特殊處理、客戶特定運送說明。內建 ShipStation-NetSuite 連接器自動同步追蹤號和運送成本，但 12 個自訂欄位不映射。有人手動複製它們，每個訂單，每天。一個自訂 MCP 模組讀取 ShipStation 自訂欄位，透過映射表轉換它們，並寫入到 NetSuite Item Fulfillment 記錄上匹配的自訂欄位 — 為運送成本進行 GL 編碼，為標籤建立提供可審查寫入計畫，並針對 V2 API 的 200 請求/分鐘上限執行每工具速率限制。

一週的探索。您獲得系統清單、工作流程地圖和固定範圍 — 無論是否與我們合作建構。