MCP — giao diện lập trình

Ngoài REST, GetMyBot còn có giao diện MCP (Model Context Protocol) — được thiết kế cho AI agent và trợ lý, vốn gọi công cụ thay vì tự gọi endpoint thủ công. REST vẫn là giao diện chính; MCP là lựa chọn tiện lợi cho các kịch bản agentic. Tên công cụ, tài nguyên và prompt dưới đây khớp với những gì server công bố.

Địa chỉ và xác thực

MCP khả dụng tại endpoint /mcp (transport Streamable HTTP, phương thức POST). Xác thực — cùng token cá nhân như với REST: header Authorization: Bearer mbp_…. Không cần tạo token riêng — một PAT hoạt động được cho cả REST lẫn MCP. Mỗi công cụ yêu cầu cùng scope với REST endpoint tương ứng; token có scope * có toàn quyền truy cập. Nếu scope không đủ — lệnh gọi bị từ chối (fail-closed), giống như trong REST.

Kết nối với Claude Code / Cursor

Thêm GetMyBot làm remote MCP server. Ví dụ cấu hình (mcpServers) — thay tên miền và token của bạn:

{
  "mcpServers": {
    "mybot": {
      "url": "https://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer mbp_YOUR_TOKEN"
      }
    }
  }
}

Claude Code: đặt khối này vào .mcp.json của dự án hoặc thêm server bằng lệnh claude mcp add. Cursor: thêm cùng khối vào cài đặt MCP (Settings → MCP → Add server). Sau khi kết nối, client sẽ tự động nhận danh sách công cụ, tài nguyên và prompt.

Công cụ theo lĩnh vực

Server công bố 100 công cụ — bao phủ toàn bộ REST khả dụng với PAT. Dưới đây là công cụ và scope yêu cầu. Tên theo định dạng động từ_danh từ (snake_case).

Bot (bots)

  • list_bots — bots:read
  • get_bot — bots:read
  • validate_bot_token — bots:write
  • connect_bot — bots:write
  • update_bot — bots:write
  • delete_bot — bots:write
  • sync_bot — bots:write
  • change_bot_token — bots:write
  • transfer_bot — bots:write
  • get_bot_settings — settings:read
  • update_bot_settings — settings:write

Kênh và template WhatsApp (bots)

Hỗ trợ đa kênh (Telegram + WhatsApp + VK) cũng khả dụng qua MCP. Kênh và template được kiểm soát bởi scope dùng chung bots:read / bots:write — không có scope kênh riêng.

  • list_channels — bots:read — liệt kê các kênh của một bot (nền tảng tg/wa/vk, external_id, tên, enabled, callback_url).
  • connect_channel — bots:write — kết nối một kênh WhatsApp hoặc VK (platform + thông tin xác thực).
  • delete_channel — bots:write — ngắt kết nối một kênh.
  • list_wa_templates — bots:read — danh mục template WhatsApp của kênh (tên, ngôn ngữ, trạng thái, danh mục, body).
  • sync_wa_templates — bots:write — đồng bộ lại danh mục template với Meta.
  • create_wa_template — bots:write — tạo một template WhatsApp và gửi tới Meta để kiểm duyệt.
  • update_wa_template — bots:write — chỉnh sửa một template (ở trạng thái APPROVED/REJECTED/PAUSED).
  • delete_wa_template — bots:write — xóa một template.

Kênh Telegram được kết nối qua connect_bot, không phải connect_channel — cái sau chỉ xử lý wa và vk. Danh mục template: MARKETING / UTILITY / AUTHENTICATION. create_wa_template gửi ngay bản nháp tới Meta để kiểm duyệt; trạng thái thay đổi một cách bất đồng bộ — đọc lại qua list_wa_templates (làm mới danh mục bằng sync_wa_templates nếu cần).

Việc tải lên media header của template (hình ảnh/video/tài liệu) qua MCP hiện chưa được hỗ trợ — hãy dùng giao diện web hoặc REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Phản ứng (reactions)

  • list_reactions — reactions:read
  • get_reaction — reactions:read
  • create_reaction — reactions:write
  • update_reaction — reactions:write
  • delete_reaction — reactions:write
  • import_reactions — reactions:write
  • test_formula — reactions:write
  • reorder_reaction — reactions:write
  • get_reaction_links — reactions:read
  • list_reaction_folders — reactions:read
  • create_reaction_folder — reactions:write
  • update_reaction_folder — reactions:write
  • delete_reaction_folder — reactions:write
  • add_reaction_to_folder — reactions:write
  • remove_reaction_from_folder — reactions:write
  • add_reactions_to_folder — reactions:write

Import qua import_reactions tạo phản ứng nhưng bỏ qua media: trong ngữ cảnh MCP không có kiểm tra premium và không có Telegram receiver cho file. Nếu bundle SamBot có ảnh/video/tài liệu — hãy dùng REST import đầy đủ (POST /api/bots/{botID}/reactions/import), công cụ này chuyển cả media.

Phát đi (broadcasts)

  • start_broadcast — broadcasts:write (tùy chọn paid, tùy chọn phân đoạn theo nhãn)
  • get_broadcast — broadcasts:write
  • pause_broadcast — broadcasts:write
  • resume_broadcast — broadcasts:write
  • cancel_broadcast — broadcasts:write

Nhãn (labels)

  • list_labels — labels:read
  • create_label — labels:write
  • delete_label — labels:write
  • set_label_favorite — labels:write

Bộ sưu tập và bản ghi (collections)

  • list_collections — collections:read
  • create_collection — collections:write
  • update_collection — collections:write
  • delete_collection — collections:write
  • list_records — collections:read
  • create_record — collections:write
  • update_record — collections:write
  • delete_record — collections:write

Kịch bản (flows)

  • list_flows — flows:read
  • get_flow — flows:read
  • create_flow — flows:write
  • update_flow — flows:write
  • delete_flow — flows:write

Tích hợp, kết nối, thông tin xác thực (integrations)

  • list_integrations — integrations:read
  • get_integration_sheets — integrations:read
  • get_integration_status — integrations:read
  • create_integration — integrations:write
  • update_integration — integrations:write
  • delete_integration — integrations:write
  • rotate_integration_token — integrations:write
  • list_connections — integrations:read
  • create_connection — integrations:write
  • test_connection — integrations:write
  • update_connection — integrations:write
  • delete_connection — integrations:write
  • list_credentials — integrations:read
  • create_credential — integrations:write
  • update_credential — integrations:write
  • delete_credential — integrations:write

Media (media)

  • upload_media — media:write
  • get_media — media:write

Template (templates)

  • list_templates — templates:read
  • delete_template — templates:write
  • create_template_from_bot — templates:write
  • apply_template — templates:write

Người đăng ký, cuộc trò chuyện, hội thoại — đọc (subscribers)

  • list_subscribers — subscribers:read (phân trang offset/limit, lọc theo nhãn)
  • list_chats — subscribers:read
  • list_dialogs — subscribers:read
  • read_dialog — subscribers:read
  • send_dialog_message — subscribers:write
  • send_dialog_reaction — subscribers:write
  • transcribe_dialog_message — subscribers:write

Thống kê và phân tích (stats)

  • get_stats — stats:read
  • get_stats_summary — stats:read
  • get_stats_recent — stats:read
  • get_stats_log — stats:read
  • get_reaction_health — stats:read
  • get_analytics — stats:read
  • get_analytics_chats — stats:read
  • get_funnel — stats:read

Thanh toán — đọc (billing)

  • get_balance — billing:read
  • list_tariffs — billing:read
  • get_transactions — billing:read

Gửi tin nhắn

  • send_message — broadcasts:write — gửi tin nhắn nhân danh bot; số dư được tính tự động theo chủ sở hữu token.

Tài nguyên

Ngoài công cụ, server còn cung cấp tài nguyên — bạn có thể đọc chúng để không cần đoán cấu trúc:

  • mybot://openapi.yaml — OpenAPI spec đầy đủ (giống với những gì trả về tại /openapi.yaml).
  • mybot://reference — tài liệu tham khảo gọn: danh sách công cụ với scope và quy ước (địa chỉ gốc, phân trang, định dạng lỗi, giới hạn).
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection — JSON schema của các cấu hình. Hữu ích nhất để tạo phản ứng (trình kích hoạt, điều kiện, cuộc trò chuyện, hành động), kịch bản và bộ sưu tập chính xác.
  • mybot://bots — danh sách bot động của bạn (ngữ cảnh nhanh mà không cần gọi công cụ).

Prompt

Các kịch bản sẵn có (slash-command trong MCP client):

  • setup_autoresponder — tạo bot tự trả lời (tham số: bot, chủ đề/bộ câu hỏi).
  • segment_broadcast — phát đi theo phân đoạn nhãn (tham số: bot, nhãn, phản ứng/văn bản).
  • diagnose_reaction — tìm hiểu tại sao phản ứng không kích hoạt (đọc phản ứng, reaction-health và thứ tự).
  • import_from_sambot — thực hiện import bundle SamBot và kiểm tra kết quả.
  • weekly_report — tổng hợp thống kê/phân tích bot theo kỳ.

Khi nào chọn MCP, khi nào chọn REST

  • Bạn viết tích hợp, đồng bộ, script hoặc bảng điều khiển riêng — dùng REST.
  • Bạn kết nối GetMyBot với AI assistant hoặc agent hỗ trợ MCP — dùng /mcp.

Cả hai giao diện đều hoạt động với cùng một token và tuân theo cùng quyền hạn của chủ sở hữu. Nếu không tìm thấy công cụ phù hợp với tác vụ — REST endpoint tương ứng luôn có trong tài liệu tham khảo tương tác.

Bước tiếp theo