用 MCP 將 AI 代理連接到 HubSpot：第一方伺服器未解決的問題

問題：12 個工具解決連接，而非含義

HubSpot 於 2026 年 4 月 13 日將其遠端 MCP 伺服器推向正式發布。它透過 OAuth 2.1 with PKCE 將 Claude、ChatGPT、Cursor 或任何 MCP 相容的 AI 客戶端連接到 HubSpot 入口，在 mcp.hubspot.com 端點進行認證。它在所有 hub 和層級中免費。它公開了 12 個工具，支援對標準 CRM 物件——聯絡人、公司、交易、工單、產品、行項目、發票、報價、訂單、購物車、訂閱、細分——以及互動歷史（通話、郵件、會議、筆記、任務）的讀寫存取。它還讀取行銷活動指標、落地頁、網站頁面和部落格文章。HubSpot 官方文件確認每個操作都尊重已連接使用者現有的 HubSpot 權限——它不是後門。

這是一個真正的產品，不是演示。對於想要問 Claude「總結所有處於『決策者已購買』階段且交易價值超過 $1,000 的未結交易」的銷售代表，第一方伺服器可以處理。HubSpot 還發布了一鍵 Claude 連接器（2026 年 7 月 16 日），讓任何擁有付費 Anthropic 訂閱的 HubSpot 使用者無需編寫程式碼即可將其 CRM 連接到 Claude 的聊天介面。設定只需幾分鐘。

問題不在於第一方伺服器做錯了什麼。問題在於它根本沒做的事情。Daeda Tech 的分析（2026 年 4 月 14 日，5 月 22 日更新）直接指出了缺口：「缺口不是關於官方 MCP 做錯了什麼——而是關於它根本沒做的事情。」這些都不是 bug。它們是產品範圍決策。HubSpot 發布了一個堅實、安全的起點。但對於執行自訂物件、工作流自動化或多入口操作的中型 B2B 公司來說，第一方伺服器覆蓋了簡單的一半，將困難的一半留給了自訂模組。

六個能力缺口

Daeda Tech 和 Scalekit 的對比（2026 年 6 月 2 日）記錄了生產使用中的缺口。它們對應到與 NetSuite MCP 模組分析中出現的相同結構模式：供應商的第一方連接器解決了連接問題。它沒有解決語意層問題——資料所說的與業務所意指的之間的差距。

1. 沒有自訂物件

遠端 MCP 伺服器僅公開標準 CRM 物件類型。如果你的入口依賴自訂物件來管理續訂、合作夥伴關係、產品使用追蹤或任何特定產業的資料模型，官方 MCP 無法看到或觸及它們。Scalekit 確認：「企業級 HubSpot 帳戶很少是開箱即用的——專業服務公司、醫療科技公司 和收入營運團隊通常在自訂物件上建構核心資料模型。」缺口文件不足：沒有錯誤代碼指示「這是一個自訂物件。」代理只是無法存取資料。HubSpot 社群論壇在 2026 年 3 月記錄了這一點——開發者透過故障排除而非文件發現了它。唯一的變通方法是直接 API，這意味著代理需要自訂模組才能存取它。

2. 沒有可審查的寫入計畫

第一方伺服器透過 manage_crm_objects 立即執行寫入。沒有草稿、沒有批次審查、沒有作為批次的撤銷用於多步驟變更。一個要求 Claude「將所有『演示階段』的交易移至『已發送提案』」的銷售代表會得到立即的、不可逆的變更。對於需要在提交前審查批次管道變更的 RevOps 團隊——因為錯誤的階段移動會扭曲預測報告並觸發下游工作流自動化——缺乏審查門是一個生產風險。Daeda AI 將此稱為「帶人工審查的寫入計畫」——AI 起草一個結構化計畫，人工審查並批准，然後計畫執行。第一方伺服器沒有等價物。

3. 每個連接一個入口

OAuth 2.1 將一個使用者認證到一個入口。管理五個 HubSpot 入口的代理商或顧問需要五個獨立的 OAuth 連接、五個權杖刷新週期和五個 AI 客戶端中的上下文切換。沒有工作區模型。對於管理多個客戶 HubSpot 實例的 B2B 服務公司，這是一個不可擴展的營運約束。自訂模組可以在內部處理多入口路由——代理呼叫 get_deals(portal_id, ...)，模組解析正確的憑證、權杖和端點。第一方伺服器做不到。

4. 沒有系統級設計

第一方伺服器僅限於記錄級別。它無法透過對話設計管道、生命週期階段、工作流邏輯或清單條件。一個想要問代理「在『合格』和『已發送提案』之間建立一個名為『採購審查』的新管道階段，並將所有超過 $50K 的交易移入其中」的 RevOps 領導者，無法透過 MCP 伺服器做到。HubSpot 直接 API 支援 Workflow Automation API v4 和管道管理——但 MCP 伺服器不公開這些端點。系統設計是直接 API 操作，這意味著它需要自訂模組才能從代理存取。

5. 每次查詢都即時命中 API

第一方伺服器沒有本地資料層。每次工具呼叫都往返於 HubSpot 伺服器。Daeda Tech 指出：「對於大型分析，延遲和分頁會累積。」search_crm_objects 工具每頁回傳最多 200 條結果。跨數千條記錄的跨物件分析意味著分頁遍歷數十次 API 呼叫，每次都增加延遲，每次都受速率限制。對於提取每筆交易、其關聯聯絡人、其互動歷史和其公司屬性的季度管道審查，僅即時 API 的模式會產生一個緩慢的代理，它在思考中途停下來等待下一頁。帶有託管資料層的自訂模組將入口資料同步到本地資料庫，並在幾秒內執行跨物件查詢——沒有每次問題的 API 往返，沒有思考中途的分頁。

6. 敏感資料約束

如果 HubSpot 帳戶啟用了「敏感資料」開關——在醫療和金融服務中很常見，處理個人健康資訊的帳戶必需——MCP 伺服器會阻止所有互動物件：通話、郵件、會議、筆記和任務。CRM 物件仍然可存取，但賦予聯絡人或交易上下文的互動歷史消失了。官方文件直接確認了這一點：「如果啟用了敏感資料，活動物件（通話、郵件、會議、筆記、任務）將被阻止從 MCP 伺服器存取。」Claude 連接器設定指南重複了同樣的約束。帶有特定 scope 的直接 CRM API 可以存取敏感資料屬性——但 MCP 伺服器不能。需要代理讀取客戶記錄通話筆記的醫療 B2B 公司在協定層被阻止，而不是在權限層。

認證：無頭代理問題

遠端 MCP 伺服器獨占性地強制 OAuth 2.1 with PKCE。沒有私有應用權杖路徑。Scalekit 的分析指出了後果：「直接 API 同時支援 OAuth 2.0 和私有應用存取權杖——後者是無頭、排程或背景代理唯一可行的認證方法，它們無法完成基於瀏覽器的同意流程。」

PKCE 需要基於瀏覽器的同意流程——一個人在重新導向 URL 中點擊「允許」，HubSpot 發出授權碼，客戶端將其交換為權杖。刷新權杖是單次使用的，每次刷新時輪換。這對於互動式使用是安全的。對於在凌晨 2 點執行以將隔夜交易變更同步到資料倉儲的背景代理，或每小時檢查停滯交易並建立跟進任務的排程工作流來說，這是不可行的。當權杖過期時，沒有人在那裡點擊「允許」。

HubSpot 直接 API 支援私有應用存取權杖——帶有 scope 的 bearer 權杖，沒有重新導向，沒有瀏覽器，沒有同意流程。這些是無頭代理和排程工作流真正需要的。自訂 MCP 模組可以透過私有應用權杖進行無人值守操作認證，透過 OAuth 2.1 進行互動式代理工作階段認證——模組在內部處理認證路徑，代理呼叫 get_deals 並且不知道也不關心正在使用哪個憑證。

速率限制加劇了這個問題。HubSpot 的 API 使用指南對 Free/Starter 的私有應用設定每 10 秒 100 次請求，Professional/Enterprise 為每 10 秒 190 次。同樣的限制適用於 MCP 伺服器請求——它們在底層執行相同的 CRM Search API。一個對 Free/Starter 入口並行發起 30 次工具呼叫的代理將失敗其中三分之一。第一方伺服器回傳 429，除了 MCP 客戶端實作的內容外，沒有結構化的重試指導。自訂模組強制執行每工具速率限制——每個工具宣告自己的限制，骨幹節點進行節流，代理收到帶有 Retry-After 標頭的結構化 429，而不是崩潰。

自訂 MCP 模組提供什麼

模組模式遵循 MCP 模組程式碼標準：每個工具都有型別化的輸入 schema、型別化的輸出 schema、速率限制、稽核日誌和錯誤契約。代理透過名稱和結構化參數呼叫工具，而不是對原始端點的自由格式 API 呼叫。

對於 HubSpot，自訂模組填補了六個缺口：

自訂物件。 模組公開了對自訂物件 schema 的型別化操作——get_renewal_record(renewal_id)、search_custom_objects(object_type, filters)、update_partnership_status(partnership_id, status)。每個工具的 schema 編碼了自訂物件的屬性、關聯和業務含義。代理透過模組存取自訂物件資料，而不是透過變通方法。

可審查的寫入計畫。 模組為多步驟變更起草結構化計畫——「將 47 筆交易從『演示』移至『已發送提案』，更新其中 12 筆的關閉日期，為交易所有者建立跟進任務」——並將其路由到人工審查者進行審批。計畫是一個型別化物件，不是自由格式的文字塊。審查者批准、拒絕或修改。模組僅執行已批准的計畫並記錄每次變更。

多入口路由。 模組在每次工具呼叫時接受 portal_id 參數，並在內部解析正確的憑證、權杖儲存和端點。代理不管理 OAuth 工作階段。單次代理呼叫可以在一次遍歷中查詢五個入口的交易資料。

系統級設計。 模組將管道管理、生命週期階段設定和工作流自動化公開為型別化工具——create_pipeline_stage(pipeline_id, label, display_order, probability)、update_lifecycle_stage(contact_id, stage)、enroll_in_workflow(contact_id, workflow_id)。這些對應到第一方伺服器未公開的 HubSpot Automation API v4 和管道管理端點。

託管資料層。 模組按計畫將入口資料同步到本地資料庫——交易、聯絡人、公司、互動、自訂物件——並針對本地副本執行跨物件查詢。代理問「顯示所有在『已發送提案』狀態超過 14 天且過去 7 天沒有互動的交易」，模組在幾秒內回傳答案，而不是幾分鐘的分頁 API 呼叫。

敏感資料存取。 模組透過私有應用權杖認證，具有讀取敏感屬性所需的特定 scope——不是透過 MCP 伺服器的阻止路徑。代理讀取醫療客戶記錄上的通話筆記，因為模組使用帶有正確 scope 的直接 API，而不是第一方伺服器的全面阻止。

語意層：第一方伺服器未編碼的內容

模式與 NetSuite 分析相同。第一方連接器讓 AI 存取記錄。自訂 MCP 模組讓 AI 理解這些記錄的含義。這就是語意層——型別化 schema 告訴代理哪些交易階段對應到該公司的「已贏得收入」預測，哪些生命週期階段構成該行銷團隊的「合格線索」SLA，哪些自訂物件屬性是該客戶成功團隊流失模型的「續訂價值」。

考慮一個管道分析。第一方伺服器公開了帶過濾器群組的 search_crm_objects。代理可以找到給定階段的所有交易。它無法告訴代理的是，對於這家公司，銷售管道中的「Closed Won」階段計入收入，但續訂管道中的同一階段不計入——續訂在單獨的收入行下計算。不知道這個區別的代理會產生重複計算的預測。模組的型別化 schema 編碼了這個區別：get_revenue_pipeline_summary(period, pipeline_ids=["sales"], exclude_pipeline_ids=["renewals"])。代理收到正確的答案，因為它問的問題就是業務所意指的問題。

或者考慮生命週期階段。第一方伺服器可以讀取聯絡人的生命週期階段。它無法告訴代理，對於這家公司，聯絡人只有在填寫了公司規模欄位超過 50 人的表單後才成為「Marketing Qualified Lead」——這是一個存在於自訂工作流中的規則，而不是在生命週期階段定義中。模組在其工具 schema 中編碼了這個規則：get_qualified_leads(since_date, min_company_size=50, source="form_submission")。規則在 schema 中，不在 prompt 中。

為什麼這可以推廣

HubSpot 模式——一個擁有 12 個工具的第一方 MCP 伺服器覆蓋標準物件，供應商不提供的語意層缺口，阻止無頭代理的認證約束，以及破壞簡單並行呼叫的速率限制——是在 CRM 和 ERP 領域出現的相同結構：

• NetSuite 有一個第一方 AI Connector Service，存在準確性缺口——Oracle 自己的 FAQ 警告「AI 可能產生幻覺。始終根據源資料驗證結果。」語意缺口是哪些 GL 帳戶構成該業務的「收入」。NetSuite MCP 模組分析深入覆蓋了這一點。
• Shopify 有一個第一方 Storefront MCP 和與 Google 的 Universal Commerce Protocol，但 B2B 路徑——客戶層級定價、批量 RFQ 報價、針對 NetSuite 的庫存預留、跨管道訂單歸屬——不在第一方表面中。Shopify 連接器分析覆蓋了這一點。

Anthropic 2026 State of AI Agents Report（500+ 技術領導者，在 Novo Nordisk、Doctolib、L'Oréal、Shopify 的實際實施）將與現有系統的整合確定為代理採用的頭號障礙——46% 的組織引用它，超過資料存取（42%）、安全（40%）和模型智慧。47% 使用混合建構與購買方法：不完全預建構，不完全內部開發，而是一個他們用自訂程式碼擴充的平台。第一方 MCP 伺服器是「購買」的一半。自訂模組是「建構」的一半。在 2026 年交付生產代理的團隊是兩者兼做的團隊——第一方伺服器覆蓋它所覆蓋的，自訂模組覆蓋它未覆蓋的。

HubSpot 發布了一個堅實的第一方伺服器。對於標準物件查找和簡單更新，它足夠了。對於自訂物件、可審查寫入、無頭認證、多入口操作、系統級設計和敏感資料存取，自訂模組是生產路徑。MCP 模組程式碼標準定義了結構。HubSpot 連接器是 CRM 案例的參考實作——12 個工具讓你起步，語意層讓你達到生產。

---

一家跨五個客戶入口執行 HubSpot 的 B2B 服務公司，擁有用於續訂和合作夥伴關係的自訂物件、用於管道管理的工作流自動化，以及取決於正確區分銷售收入和續訂收入的季度預測，獲得一個代理，它能解析自訂物件記錄、為批次管道變更起草可審查的寫入計畫、為排程同步進行無頭認證、在單次工作階段中跨入口路由，並在型別化 schema 中編碼收入階段區別——每次工具呼叫都有日誌記錄，每個例外都路由到人工審查者。該建構是四步方法的第 2-3 階段，通常在 5-8 週內上線。

請求一個範圍明確的建構。 一週 Discovery。你獲得系統清單、工作流圖和固定範圍——無論你是否與我們合作建構。