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ùnglist_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ế.
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à:
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:
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 đồ
- Yêu cầu trợ lý gọi
search_map_leadsvới vị trí và từ khóa doanh nghiệp, chẳng hạn như một thành phố vàmarketing agency. - Các bộ lọc tùy chọn gồm
radiusKm(1–100),lat,lngvàemailOnlyđể chỉ giữ lại doanh nghiệp có công khai email. - Khi kết quả có
nextPageToken, hãy truyền giá trị đó dưới dạngpageTokenđể tải trang tiếp theo. - Yêu cầu trợ lý gọi
import_map_leadsvớ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.
Khởi chạy chiến dịch nháp
- 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. - Cho phép thao tác trong cuộc trò chuyện. Trợ lý gọi trực tiếp
launch_campaignvới ID chiến dịch vàsendNow: trueđể gửi ngay hoặcscheduledAtvớ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. - 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_campaignvàget_campaign_statstrước khi thử lại nếu kết quả chưa rõ.
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ênradiusKm 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ùngupdate_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õ.