Chuyển đến nội dung chính

Tổng quan

Nudgen cung cấp máy chủ MCP tại điểm cuối /mcp trên miền ứng dụng. Máy chủ hỗ trợ MCP 2026-07-28 qua Streamable HTTP và yêu cầu OAuth 2.1. Đăng nhập qua trình duyệt và phê duyệt các quyền được yêu cầu. Khi tính năng có sẵn, bạn có thể chọn một workspace hoặc cấp quyền rõ ràng cho tất cả workspace hiện tại và tương lai mà bạn là thành viên. Đổi workspace trong dashboard không đổi workspace mặc định của MCP.

Làm việc với nhiều workspace

Kết nối hiện có vẫn chỉ truy cập workspace ban đầu cho đến khi bạn kết nối lại và cấp quyền rộng hơn. Với quyền truy cập tất cả workspace, các workspace bạn tham gia sau này tự động khả dụng; mất tư cách thành viên sẽ chặn các thao tác tiếp theo trong workspace đó. Vai trò, gói đăng ký và hạn mức vẫn áp dụng riêng cho từng workspace. Dùng list_workspaces với page và pageSize để xem ID, tên, slug, vai trò và workspace mặc định. Công cụ yêu cầu teams:read. Thêm workspaceId vào lời gọi công cụ để chọn workspace cho riêng thao tác đó. Nếu bỏ qua, công cụ dùng workspace mặc định của kết nối. Khi xem và gửi chiến dịch, hãy truyền cùng một ID workspace cụ thể. Chọn workspace mặc định khi cấp quyền OAuth. Đổi lựa chọn trong Cài đặt → Khóa API → Ứng dụng MCP đã kết nối hoặc gọi set_default_workspace với workspaceId và quyền teams:write. Thay đổi này áp dụng cho mọi cuộc trò chuyện dùng cùng kết nối. Chọn workspace cho riêng một thao tác không đổi mặc định. Nếu workspace mặc định bị xóa hoặc không còn truy cập được, hãy truyền một ID khác hoặc cập nhật mặc định; Nudgen không tự chọn workspace thay thế.
URI tài nguyên hiện có dùng workspace mặc định. Các mẫu sau chọn workspace cụ thể:

Tại sao điều này lại quan trọng

Trợ lý có thể xem danh bạ, tìm doanh nghiệp và tạo chiến dịch nháp. Bạn cho phép gửi hoặc lên lịch ngay trong cuộc trò chuyện; trợ lý thực hiện trực tiếp, không cần liên kết phê duyệt trên trình duyệt.

Kết nối client

Điểm cuối production là:
Thêm điểm cuối này dưới dạng máy chủ MCP HTTP từ xa trong một client hỗ trợ OAuth. Client sẽ tìm máy chủ ủy quyền của Nudgen từ điểm cuối rồi mở quy trình đăng nhập và chấp thuận trong trình duyệt. Chọn workspace mà bạn muốn client truy cập và chỉ phê duyệt các phạm vi quyền cần thiết. Các tài liệu khám phá: Máy chủ ủy quyền sử dụng authorization code với PKCE S256, liên kết tài nguyên và xoay vòng refresh token. Máy chủ chấp nhận Client ID Metadata Documents và đăng ký client động. Với Codex CLI, hãy dùng:
Nếu một client có tên nudgen đã được cấu hình, hãy cập nhật mục đó bằng URL /mcp. Dùng campaigns:read để xem dữ liệu, campaigns:write để tạo và sửa bản nháp, và campaigns:send cho các thao tác gửi đã được bạn cho phép. Vẫn cần cấp quyền OAuth khi kết nối.
Mã thông báo truy cập cá nhân xác thực API nhà phát triển, nhưng không xác thực /mcp. Client MCP phải hoàn tất quy trình đăng nhập OAuth.

Công cụ có sẵn

create_campaign lưu một chiến dịch ở dạng bản nháp (one-time, drip hoặc lifetime). Công cụ này không thể gửi hoặc lên lịch trực tiếp. get_campaign cho phép bạn kiểm tra tiêu đề, nội dung, liên kết, đối tượng và người gửi trước khi khởi chạy. Máy chủ cũng cung cấp các tài nguyên chỉ đọc trong phạm vi campaigns:read:

Tìm và nhập khách hàng tiềm năng trên bản đồ

  1. Yêu cầu trợ lý gọi search_map_leads với vị trí và từ khóa doanh nghiệp, chẳng hạn như một thành phố và marketing agency.
  2. Các bộ lọc tùy chọn gồm radiusKm (1–100), lat, lng và emailOnly để chỉ giữ lại doanh nghiệp có công khai email.
  3. Khi kết quả có nextPageToken, hãy truyền giá trị đó dưới dạng pageToken để tải trang tiếp theo.
  4. Yêu cầu trợ lý gọi import_map_leads với cùng vị trí và từ khóa, cùng các đối tượng khách hàng tiềm năng cần lưu. Mỗi lần gọi chấp nhận tối đa 200 khách hàng tiềm năng.
Thao tác nhập sẽ ghi liên hệ vào workspace đã kết nối. Khách hàng tiềm năng không có email sẽ bị bỏ qua. Khách hàng tiềm năng đã tồn tại sẽ được cập nhật.

Khởi chạy chiến dịch nháp

  1. Xem tên chiến dịch, tiêu đề, nội dung, người gửi thực tế, số người nhận ước tính và thời gian bằng get_campaign.
  2. Cho phép thao tác trong cuộc trò chuyện. Trợ lý gọi trực tiếp launch_campaign với ID chiến dịch và sendNow: true để gửi ngay hoặc scheduledAt với thời điểm tương lai kèm múi giờ. Không truyền các lựa chọn thời gian mâu thuẫn. Không cần xác nhận lại nếu bạn đã cho phép.
  3. Xem trạng thái, thời gian lên lịch và liên kết dashboard trả về. Đã xếp hàng hoặc đã lên lịch không có nghĩa là đã gửi đến người nhận. Kiểm tra get_campaign và get_campaign_stats trước khi thử lại nếu kết quả chưa rõ.
Nudgen vẫn kiểm tra quyền workspace, người gửi, người nhận đủ điều kiện, gói đăng ký, hạn mức, phiên bản chiến dịch và hàng đợi. Tạo và sửa chiến dịch chỉ lưu bản nháp; việc gửi cần worker chiến dịch.

Quản lý quyền truy cập

Mở Cài đặt → Khóa API → Ứng dụng MCP đã kết nối để xem quyền, đổi mặc định hoặc ngắt kết nối. Ngắt kết nối nhiều workspace sẽ thu hồi token và mã cấp quyền đang chờ của kết nối đó trên mọi workspace, không ngắt các kết nối REST riêng. OAuth REST và trợ lý trong ứng dụng giữ nguyên phạm vi workspace hiện có.

Khắc phục sự cố

Đối với tập lệnh dùng bearer token và các điểm cuối REST trực tiếp, hãy xem API nhà phát triển.

Bán kính tìm kiếm và bổ sung thông tin

Tìm kiếm API và MCP mặc định 5 km, chấp nhận số nguyên radiusKm từ 1 đến 100 và không hiển thị hộp thoại xác nhận của bảng điều khiển. Giữ nguyên tham số khi truyền nextPageToken thành pageToken; một trang không có kết quả phù hợp vẫn có thể có trang tiếp theo. Thông tin liên hệ có thể được bổ sung sau khi doanh nghiệp xuất hiện. enrichmentPending đánh dấu việc nghiên cứu website chưa hoàn tất. Xem businessSummary và businessSources khi có; ngữ cảnh doanh nghiệp được nhập có thể hỗ trợ lời mở đầu cá nhân hóa. Chưa có email có thể do nghiên cứu còn đang chờ. Nếu có enrichmentRetryToken, gọi retry_map_leads_enrichment với token. Công cụ cần campaigns:read, gắn với không gian làm việc đã kết nối, hết hạn sau 15 phút và chỉ dùng một lần. Hợp nhất kết quả theo placeId trước khi nhập. emailOnly lọc phản hồi hiện tại; khách hàng đang chờ có thể xuất hiện sau khi thử lại.

Sửa bản nháp và phạm vi công cụ

Dùng update_campaign để sửa bản nháp hiện có và delete_campaign để xóa bản nháp. Cả hai yêu cầu campaigns:write; không công cụ nào gửi hoặc lên lịch email. Các nhóm chức năng mới yêu cầu quyền OAuth riêng. Kết nối lại và phê duyệt các quyền đó khi được yêu cầu. Danh sách công cụ cho biết công cụ và tham số khả dụng. Chuyển sang trình duyệt không tự thực hiện thao tác: dùng trình duyệt để thanh toán, cấp quyền nhà cung cấp, gửi lời mời, tạo/xóa/tham gia workspace và sửa thông tin chi trả nhạy cảm. Chọn workspace hoặc đổi mặc định qua MCP không đổi workspace của dashboard. Chức năng quản trị, thông tin xác thực, webhook, callback theo dõi và trợ lý nội bộ không được cung cấp. Dùng get_api_capabilities để xem phạm vi API. Sau khi được bạn cho phép trong cuộc trò chuyện, gọi trực tiếp send_test_email, activate_lifetime_campaign hoặc trigger_lifetime_campaign. Email thử chỉ gửi đến email tài khoản. Kích hoạt lifetime cho phép tự động gửi về sau. Không cần phê duyệt trên trình duyệt hoặc mã phê duyệt. Kiểm tra trạng thái hoặc lịch sử thực thi trước khi thử lại nếu kết quả chưa rõ.