HubSpot MCP Setup: Cursor | AgenticSkillset.org

Điểm khác biệt lớn nhất khi dùng HubSpot MCP qua Cursor so với các CLI agent khác: AI nhìn thấy đồng thời cả source code của bạn và dữ liệu CRM thật trong cùng một cửa sổ — không cần chuyển qua chuyển lại giữa editor và HubSpot UI. Điều này biến Cursor thành công cụ mạnh cho một việc rất cụ thể: đưa engineer tới gần khách hàng hơn ngay trong lúc code, thay vì đọc ticket một lần rồi quên mất context khi bắt đầu implement. Bài này hướng dẫn kết nối HubSpot MCP vào Cursor Agent Mode, cách liên kết ticket với code/backlog, sinh code tích hợp dựa trên schema HubSpot thật, và các giới hạn cần biết.

Kết Nối HubSpot MCP Vào Cursor Agent Mode

Cursor hỗ trợ MCP qua .cursor/mcp.json ở project hoặc ~/.cursor/mcp.json ở global:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@hubspot/mcp-server"],
      "env": {
        "PRIVATE_APP_ACCESS_TOKEN": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Mở Cursor Settings → MCP, xác nhận server "hubspot" hiển thị trạng thái xanh (connected) — đây cũng là nơi bạn tắt/bật từng tool riêng lẻ, nên tắt hẳn các tool ghi (create-note, update-object) trong giai đoạn đầu làm quen để tránh Cursor Agent tự gọi mà không hỏi lại.

Để dùng, mở Agent Mode (Cmd/Ctrl + I), gõ yêu cầu bình thường — Cursor tự quyết định khi nào cần gọi tool HubSpot dựa trên ngữ cảnh câu hỏi và code đang mở:

@codebase Tôi đang implement webhook xử lý event "deal.propertyChange" cho
dealstage. Lấy schema thực tế của object Deal trong HubSpot của tôi (tên
property, type, các giá trị enum của dealstage) để tôi map đúng vào code.

Mẹo: Trong Cursor Settings → MCP, tắt hẳn tool delete-object và các tool ghi khác trong giai đoạn đầu — Cursor Agent Mode có thể tự quyết định gọi tool mà không hỏi lại từng bước như một số CLI agent, và với dữ liệu CRM sản xuất thật, một lệnh ghi sai có hậu quả thực tế cho khách hàng.

Liên Kết Ticket Khách Hàng Với Khu Vực Code và Backlog Item

Vấn đề kinh điển: ticket support mô tả vấn đề bằng ngôn ngữ khách hàng ("app bị treo khi export báo cáo lớn"), còn engineer cần biết chính xác vùng code nào liên quan để ước lượng độ khó fix. Với Cursor nhìn thấy cả code và HubSpot MCP cùng lúc, bạn rút ngắn khoảng cách này:

Đọc ticket "App bị treo khi export báo cáo hơn 10000 dòng" (ticket ID
HS-4821). Dựa trên mô tả, tìm trong codebase các file liên quan tới
chức năng export báo cáo, và cho biết khả năng nguyên nhân kỹ thuật là gì.

Agent gọi get-object để lấy nội dung ticket, sau đó dùng @codebase để tìm file liên quan (ví dụ ExportService.java, ReportGenerator.ts), rồi đối chiếu logic hiện tại với mô tả triệu chứng.

Sau khi xác định được nguyên nhân sơ bộ, bước tiếp theo là tạo backlog item có liên kết ngược:

Từ phân tích trên, viết một backlog item (dạng markdown) gồm: Title,
Mô tả kỹ thuật ngắn, File liên quan, Mức độ ưu tiên đề xuất (dựa trên
việc ticket này company nào report và deal amount của company đó).
Kèm link tham chiếu tới ticket HS-4821 để dễ tra lại nguồn gốc.

Việc giữ link ngược tới ticket gốc trong backlog item quan trọng hơn nhiều người nghĩ — khi engineer khác pick up task này sau vài tuần, họ cần đọc lại đúng lời khách hàng mô tả, không chỉ bản diễn giải đã qua một lớp tóm tắt.

Mẹo: Luôn yêu cầu agent giữ nguyên ticket ID hoặc link HubSpot trong mọi backlog item được tạo từ ticket. Đây là "audit trail" rẻ nhất bạn có thể có — giúp trả lời câu hỏi "tại sao chúng ta build cái này" một cách chính xác nhiều tháng sau.

Sinh Code Tích Hợp Dựa Trên Schema Object Thật Của HubSpot

Khi bạn cần viết code tích hợp với HubSpot (webhook handler, đồng bộ dữ liệu hai chiều, script báo cáo nội bộ), việc có AI đọc trực tiếp schema thật — bao gồm cả custom property riêng của công ty bạn — giúp code sinh ra đúng ngay từ lần đầu, thay vì đoán theo tài liệu HubSpot chung không biết custom field của bạn.

Tôi cần viết một hàm TypeScript nhận webhook "contact.propertyChange" từ
HubSpot, kiểm tra nếu property "lifecyclestage" chuyển thành "customer",
thì gọi API nội bộ để tạo account trong hệ thống billing của chúng tôi.
Trước khi viết code, lấy schema property "lifecyclestage" thực tế
(các giá trị enum hợp lệ) để tôi chắc chắn switch-case cover đủ case.

Agent gọi tool schema (crm.schemas qua HubSpot MCP) để lấy đúng danh sách giá trị enum hiện tại của property — tránh trường hợp code viết theo tài liệu public nhưng công ty bạn đã tuỳ biến thêm giá trị custom cho lifecyclestage.

Một use case khác: sinh code kiểm tra tính nhất quán dữ liệu giữa hệ thống nội bộ và HubSpot:

Viết một script Node.js chạy định kỳ, so sánh danh sách company_id
trong database nội bộ (bảng "customers") với company trong HubSpot
(match theo domain), báo cáo các company có trong DB nội bộ nhưng
chưa có trong HubSpot hoặc ngược lại.

Mẹo: Luôn yêu cầu agent lấy schema thật trước khi viết code xử lý enum/property tuỳ biến, đừng để nó tự đoán theo tài liệu HubSpot mặc định. Custom property khác nhau giữa từng tài khoản HubSpot là nguyên nhân phổ biến nhất khiến code tích hợp chạy đúng lúc test nhưng lỗi khi gặp giá trị thực tế trong production.

Hạn Chế Đã Biết và Cách Khắc Phục Khi Dùng HubSpot MCP Trong Cursor

Agent Mode có thể gọi tool mà không hỏi xác nhận từng bước như đã nói ở phần 1 — khắc phục bằng cách tắt tool ghi trong Settings, hoặc dùng chế độ review diff trước khi apply nếu phiên bản Cursor bạn dùng hỗ trợ.
Context giới hạn khi mở nhiều file code lớn cùng lúc với việc gọi HubSpot MCP — nếu vừa mở nhiều controller, vừa đọc nhiều ticket dài, agent có thể bị cắt bớt context và bỏ sót thông tin. Nên giới hạn phạm vi file mở trong một session cho từng module cụ thể.
Không có lịch sử version cho thay đổi qua MCP — khác với code có git track từng dòng, thay đổi trên HubSpot (note, property) qua MCP chỉ có "property history" nội bộ của HubSpot cho một số loại property, không đầy đủ như git log. Với thay đổi quan trọng, vẫn nên có review tay.
Rate limit HubSpot API dễ chạm khi vừa code vừa truy vấn CRM liên tục trong một session dài — nếu gặp lỗi 429 thường xuyên, giảm tần suất gọi tool bằng cách gộp câu hỏi thành ít lượt hơn.

Mẹo: Với tác vụ liên quan tới property nhạy cảm (billing, lifecyclestage ảnh hưởng tự động hoá downstream), bật review mode nghiêm ngặt hơn: yêu cầu Cursor Agent chỉ đề xuất thay đổi dưới dạng plan text trước, bạn duyệt bằng lời rồi mới cho phép gọi tool ghi thật vào HubSpot.

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

Tắt hoàn toàn tool ghi trong Settings → MCP cho tới khi bạn thực sự cần agent tự cập nhật CRM — mặc định nên là read-only trong mọi project mới.
Luôn yêu cầu agent lấy schema thật (property, enum) trước khi sinh code xử lý dữ liệu HubSpot, đừng để nó đoán theo tài liệu public.
Giữ ticket ID/link HubSpot trong mọi backlog item hoặc comment code sinh ra từ phân tích ticket — đây là audit trail rẻ và hữu ích nhất bạn có thể duy trì.
Với session dài vừa code vừa truy vấn CRM liên tục, theo dõi số lượng tool call để tránh chạm rate limit HubSpot giữa lúc đang tập trung debug.

Mẹo: Thêm một mục riêng trong .cursor/rules hoặc file hướng dẫn project mô tả rõ: tool HubSpot nào được allow, quy tắc PII khi sinh báo cáo, và yêu cầu luôn giữ link ticket gốc. Việc này giúp mọi engineer dùng Cursor trong team tuân theo cùng chuẩn khi chạm vào dữ liệu khách hàng, không phụ thuộc vào việc từng người có nhớ nhắc lại quy tắc hay không.