Kết nối Claude Code với SePay qua MCP

Hướng dẫn kết nối Claude Code với SePay qua MCP trên dòng lệnh, để tra cứu giao dịch, webhook, tài khoản ngân hàng và tài liệu tích hợp SePay...

||

Bạn thêm SePay vào Claude Code bằng lệnh claude mcp add lấy trên SePay, rồi đăng nhập SePay qua trình duyệt để cấp quyền.

Điều kiện trước khi bắt đầu

  1. Tài khoản Claude dùng được Claude Code: gói Pro, Max, Team, Enterprise hoặc tài khoản Console (gói Free không có Claude Code).
  2. Một terminal: Terminal trên macOS hoặc Linux, PowerShell trên Windows.
  3. Vào được trang AI Agent trên SePay, xem điều kiện trên SePay.

Các bước kết nối

Các bước viết theo giao diện Claude Code tháng 10/2026 và hướng dẫn của Anthropic. Nếu giao diện Claude Code có thay đổi, hãy tìm các mục có ý nghĩa tương tự hoặc liên hệ SePay để được hỗ trợ.

Bước 1: Cài Claude Code

Nếu gõ claude trong terminal đã chạy được thì bỏ qua bước này. Trên macOS, Linux, cài bằng lệnh:

$ curl -fsSL https://claude.ai/install.sh | bash

Trên Windows, cài bằng lệnh sau trong PowerShell:

$ irm https://claude.ai/install.ps1 | iex

Cách cài khác (Homebrew, WinGet, npm) xem hướng dẫn cài Claude Code. Cài xong, mở terminal mới rồi chạy claude và đăng nhập tài khoản Claude theo hướng dẫn trên màn hình.

Bước 2: Sao chép lệnh kết nối trên SePay

  1. Đăng nhập my.sepay.vn.
  2. Ở menu bên trái, mục Tích hợp & Thông báo, chọn AI Agent.
  3. Chọn Tạo kết nối ở góc trên bên phải.

Trang Tạo kết nối mở ra. Ở cột Bạn dùng ứng dụng AI nào?, chọn Claude Code, rồi ở ô Lệnh kết nối, chọn nút sao chép.

Trang Tạo kết nối trên my.sepay.vn đang chọn Claude Code, hiện lệnh kết nối kèm nút sao chép
Nhấn để phóng to
Chọn Claude Code rồi sao chép lệnh kết nối.

Bước 3: Thêm SePay vào Claude Code

Mở terminal trong thư mục dự án, dán lệnh vừa sao chép rồi chạy. Lệnh có dạng:

$ claude mcp add --transport http sepay https://my.sepay.vn/mcp --client-id sepay-claude-code --callback-port 8765

Lệnh chỉ thêm SePay cho thư mục đang mở. Muốn dùng SePay ở mọi thư mục trên máy, thêm --scope user vào cuối lệnh.

Bước 4: Chọn Authenticate trong Claude Code

Trong thư mục đó, chạy claude rồi gõ /mcp. Trong danh sách Quản lý máy chủ MCP (Manage MCP servers), chọn sepay rồi nhấn Enter:

Claude Code
> /mcp Manage MCP servers Local MCPs❯ sepay · △ needs authentication

Ở màn hình Sepay MCP Server, chọn 1. Xác thực (1. Authenticate) rồi nhấn Enter:

Claude Code
Sepay MCP Server Status:  △ needs authenticationAuth:    ✘ not authenticated ❯ 1. Authenticate2. Disable

Claude Code mở trình duyệt tới màn hình cấp quyền của SePay. Trình duyệt không tự mở thì sao chép đường link Claude Code in ra và dán vào trình duyệt.

Cấp quyền cho Claude Code trên SePay

Bước 5: Đồng ý cấp quyền và dán mã xác thực

Trên màn hình Claude Code muốn truy cập dữ liệu SePay của bạn:

  1. Bật hoặc tắt từng nhóm dữ liệu ở mục AI được phép xem.
  2. Nếu cần, mở Ẩn bớt thông tin cho ứng dụng này.
  3. Chọn Đồng ý cấp quyền.

Ý nghĩa từng nhóm dữ liệu và tùy chọn ẩn có ở Quyền và bảo mật SePay MCP.

Màn hình cấp quyền SePay MCP cho Claude Code: các nhóm quyền ở mục AI được phép xem, nhóm Thao tác ghi tắt sẵn và danh sách việc AI không được phép
Nhấn để phóng to
Bật nhóm dữ liệu Claude Code được đọc rồi chọn Đồng ý cấp quyền.

Trình duyệt chuyển sang trang Hoàn tất kết nối:

  1. Ở ô Mã xác thực, chọn Sao chép.
  2. Quay lại terminal, dán vào ô URL > đang chờ trong Claude Code rồi nhấn Enter.

Khi Claude Code in Authentication successful. Connected to sepay., kết nối đã xong.

Trang Hoàn tất kết nối của SePay cho Claude Code với ô Mã xác thực và nút Sao chép
Nhấn để phóng to
Sao chép mã xác thực rồi dán vào ô URL > trong Claude Code.

Hỏi thử Claude Code về dữ liệu SePay

Trong Claude Code, hỏi thử, ví dụ "Cho tôi 10 giao dịch gần đây". Lần đầu, Claude Code có thể hỏi bạn có cho dùng công cụ của SePay không: chọn Có (Yes). Khi Claude Code in dòng Called sepay rồi trả về bảng giao dịch, kết nối đã chạy. Ở đây sepay là tên bạn đặt cho SePay MCP trong lệnh ở Bước 3, không phải SePay CLI.

Tra cứu tài liệu tích hợp SePay

Claude Code đọc được tài liệu trên developer.sepay.vn qua SePay MCP, kể cả khi chưa cấp quyền. Khi bạn hỏi về tích hợp, Claude Code đọc trang tài liệu liên quan rồi trả lời kèm link trang đó. Mở link để đối chiếu trước khi dùng code. Ví dụ:

  • "Webhook SePay gửi những trường nào, xác thực bằng API Key thế nào?"
  • "Tạo QR thanh toán có sẵn số tiền và mã đơn bằng SePay thế nào?"
  • ...

Ngắt kết nối Claude Code

Gỡ SePay khỏi Claude Code bằng lệnh sau, chạy trong thư mục dự án đã thêm SePay:

$ claude mcp remove sepay

Lệnh này không thu hồi kết nối trên SePay. Muốn thu hồi, vào trang AI Agent, xem Quản lý kết nối.

Lỗi thường gặp

Các lỗi chung của SePay MCP ở Lỗi thường gặp khi kết nối SePay MCP.

Tiếp theo