·

HubSpot MCP với OpenCode

Cài đặt HubSpot MCP trong OpenCode để AI agent có thể quản lý contact, deal và ticket ngay trong trình soạn thảo.

OpenCode là agentic coding tool mã nguồn mở, cho phép tự chọn model backend và có cơ chế cấu hình permission theo từng tool khá chi tiết qua file opencode.json. Với HubSpot MCP — nơi mỗi tool call có thể chạm vào dữ liệu khách hàng thật — khả năng kiểm soát permission chi tiết của OpenCode là một lợi thế thực sự, không chỉ là tính năng "cho vui". Bài này hướng dẫn cấu hình, cách đọc CRM object và association, một ví dụ thực tế tổng hợp complaint từ ticket, và các hạn chế cần biết khi dùng OpenCode cho tác vụ CRM.

Cài Đặt và Kết Nối HubSpot MCP Với OpenCode

OpenCode đọc cấu hình MCP từ opencode.json (root project hoặc global ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hubspot": {
      "type": "local",
      "command": ["npx", "-y", "@hubspot/mcp-server"],
      "environment": {
        "PRIVATE_APP_ACCESS_TOKEN": "{env:HUBSPOT_TOKEN}"
      },
      "enabled": true
    }
  }
}

Khác với Claude Code, OpenCode dùng key mcp (không phải mcpServers) và field type: "local" để chỉ rõ đây là server chạy dạng process con qua stdio. Đặt HUBSPOT_TOKEN trong biến môi trường shell hoặc .env được OpenCode tự load.

Sau khi cấu hình, khởi động OpenCode và gõ:

/mcp

để xem danh sách server đã đăng ký và trạng thái kết nối. Nếu server hiện failed, thử chạy thẳng npx -y @hubspot/mcp-server ngoài terminal để xem lỗi gốc — thường là do package chưa cài được hoặc token sai định dạng (token Private App luôn có prefix pat-).

Mẹo: Với project không liên quan tới CRM, tắt hẳn server HubSpot qua field enabled: false. Quá nhiều tool được nạp cùng lúc (đặc biệt khi bạn cũng bật GitHub MCP, Jira MCP...) làm agent dễ chọn sai tool hơn, và với HubSpot cụ thể, giảm thiểu rủi ro agent vô tình truy vấn dữ liệu khách hàng trong context không liên quan.

Đọc CRM Objects và Associations Từ OpenCode

Vì OpenCode cho phép cấu hình permission chi tiết theo từng tool, cách làm khuyến nghị với HubSpot MCP là: cho phép tự do các tool đọc, nhưng yêu cầu xác nhận với bất kỳ tool có khả năng ghi.

{
  "permission": {
    "tool": {
      "hubspot_search-objects": "allow",
      "hubspot_get-object": "allow",
      "hubspot_list-associations": "allow",
      "hubspot_create-note": "ask",
      "hubspot_update-object": "ask"
    }
  }
}

Tên tool cụ thể có thể khác đôi chút tuỳ version package, nên chạy /mcp để lấy tên chính xác trước khi cấu hình permission.

Với cấu hình trên, một truy vấn đọc + phân tích association chạy trơn tru không cần xác nhận từng bước:

Lấy company "Acme Corp", danh sách toàn bộ deal và ticket liên kết,
với mỗi ticket cho biết status và ngày tạo. Sắp xếp ticket theo ngày
tạo giảm dần.

OpenCode sẽ gọi search-objects để tìm company, list-associations hai lần (deals và tickets) — toàn bộ chuỗi này chạy tự động vì đã được "allow". Nhưng nếu bạn yêu cầu ghi lại kết luận:

Từ dữ liệu trên, viết một note tóm tắt tình trạng company này và
lưu vào record company đó trong HubSpot.

OpenCode sẽ dừng lại xin xác nhận trước khi gọi create-note — đúng tinh thần "human-in-the-loop" cho bất kỳ hành động ghi dữ liệu vào CRM sản xuất thật.

Mẹo: Giữ toàn bộ nhóm tool ghi (create-note, update-object, create-engagement) ở trạng thái "ask" trong ít nhất 2-3 tuần đầu dùng thật. Sau khi đã quen với cách agent diễn giải yêu cầu, bạn có thể chuyển các tool ít rủi ro (như create-note) sang "allow", nhưng nên giữ "ask" vĩnh viễn cho các tool có thể sửa deal/ticket.

Ví Dụ Thực Tế: Tổng Hợp Top Complaint Của Khách Hàng Từ Tickets

Đây là use case tiết kiệm thời gian rõ rệt cho product engineer cần chuẩn bị input cho buổi backlog grooming hàng tháng. Quy trình thực tế:

Bước 1 — Lấy dữ liệu thô, nhóm theo chủ đề:

Lấy tất cả ticket tạo trong 30 ngày qua ở pipeline "Customer Support",
bất kể status. Đọc subject và nội dung mô tả, nhóm thành các chủ đề
chính (ví dụ "performance", "billing confusion", "missing feature X").
Với mỗi nhóm, cho biết số lượng và mức độ nghiêm trọng trung bình (dựa
trên field priority của ticket).

Bước 2 — Đào sâu nhóm có volume cao, lấy quote thực tế:

Với nhóm "performance" (nhóm cao nhất ở trên), lấy 5 ticket đại diện,
trích quote nguyên văn phần khách hàng mô tả vấn đề (không diễn giải lại),
kèm ticket ID để tôi đối chiếu khi cần.

Bước 3 — Kiểm tra impact doanh thu để hỗ trợ ưu tiên:

Với 5 ticket ở trên, lấy company liên kết, cộng tổng deal amount đang
active hoặc closed-won của các company đó.

Bước 4 — Tổng hợp thành báo cáo gọn cho buổi grooming, chỉ cần yêu cầu agent trình bày lại toàn bộ 3 bước trên dưới dạng một đoạn tóm tắt kèm bảng số liệu — không cần chạy lại truy vấn nếu dữ liệu đã có trong context của session.

Mẹo: Luôn yêu cầu bước "trích quote nguyên văn" tách riêng khỏi bước "diễn giải/tóm tắt". Việc trộn lẫn hai bước này khiến bạn khó phân biệt đâu là điều khách hàng thực sự nói, đâu là suy luận thêm của AI — với báo cáo dùng để ra quyết định ưu tiên, sự khác biệt này quan trọng.

Các Hạn Chế Đã Biết Của HubSpot MCP Trong OpenCode

  • Model open-weight nhỏ (qua Ollama) dễ chọn sai tool khi có nhiều tool HubSpot cùng lúc (search theo nhiều loại object khác nhau) — nếu dùng model nhỏ để tiết kiệm chi phí, nên giảm số tool bật cùng lúc hoặc chỉ bật tool cho loại object đang cần.
  • Rate limit của HubSpot API (theo hạn mức request/10 giây tùy plan, thường khá thấp ở plan free/starter) khiến các truy vấn tổng hợp nhiều object (deal → company → ticket → note) dễ bị throttle nếu chạy dồn trong một prompt phức tạp — nên chia thành nhiều bước nhỏ như ví dụ ở trên.
  • Custom object và custom property (HubSpot cho phép tạo object tùy biến ngoài 5 loại tiêu chuẩn) không phải lúc nào cũng được mọi version MCP server hỗ trợ đầy đủ — kiểm tra README của package trước khi kỳ vọng agent đọc được custom object của công ty bạn.
  • Không có cơ chế redact PII tự động ở tầng MCP server — việc ẩn email/số điện thoại trong output hoàn toàn phụ thuộc vào cách bạn prompt, OpenCode (và MCP nói chung) không tự áp policy này.

Mẹo: Với các truy vấn cần chạy định kỳ (ví dụ báo cáo complaint hàng tháng), lưu prompt pattern đã hoạt động tốt thành một file cấu hình prompt riêng trong repo, và luôn review kết quả 1-2 lần đầu tiên trước khi tin tưởng chạy tự động theo lịch.

Mẹo Thực Chiến Khi Dùng HubSpot MCP Với OpenCode

  • Bắt đầu với permission tool ở mức chặt nhất (chỉ allow đọc), chỉ mở rộng quyền ghi sau khi đã quan sát agent hoạt động đúng ý qua nhiều lần dùng thật.
  • Dùng field enabled để chỉ bật HubSpot MCP trong đúng project cần dùng CRM — tránh nạp thêm tool không liên quan vào context của các project kỹ thuật thuần túy.
  • Với model chạy qua Ollama, ưu tiên dùng cho task đọc/tổng hợp đơn giản; chuyển sang model lớn hơn (Claude, GPT) khi cần agent tự lên kế hoạch gọi nhiều tool liên tiếp hoặc suy luận phức tạp trên dữ liệu CRM.
  • Ghi log lại các lần agent bị từ chối do thiếu scope hoặc rate limit — đây là dữ liệu hữu ích để tinh chỉnh lại Private App hoặc cách chia nhỏ truy vấn về sau.

Mẹo: Lưu cấu hình opencode.json cùng file permission mẫu vào repo chung của team (không kèm token thật) để mọi engineer mới join có thể copy nguyên cấu hình an toàn, thay vì tự mò lại từ đầu quyền nào nên allow, quyền nào nên ask.

Tiếp HubSpot MCP với Gemini CLI