MCP cho AI agent

7 phút đọc

Máy chủ ferry-mcp cho phép Claude và các AI agent khác làm việc với API đối tác Ferry qua giao thức Model Context Protocol: tìm chuyến, xem sơ đồ ghế và giá, tìm khách hàng, đọc booking và yêu cầu huỷ vé. Máy chủ nằm trong repo mã nguồn mở ferry-vn/ferry-sdk, cùng SDK và CLI.

Agent làm được gì

Với máy chủ này, bạn có thể nhờ Claude: “tìm chuyến Rạch Giá đi Phú Quốc ngày mai, so sánh giá”, “còn ghế liền nhau cho 4 người không”, “booking của khách số 0901… đang ở trạng thái nào” hay “báo giá booking này nhưng chưa tạo”. Máy chủ chạy bằng API key của bạn nên nhìn thấy đúng dữ liệu của tổ chức bạn; xem Xác thực bằng API key.

Ngoài công cụ, máy chủ có hai lời nhắc sẵn (plan_ferry_trip, check_booking) và một tài nguyên ferry://locations chứa danh mục bến. Môi trường mặc định là production; đặt FERRY_ENV=uat để dùng UAT, nhưng UAT không phải sandbox: xuất vé ở đó vẫn đặt vé thật và trừ tiền thật (xem Môi trường).

Cài đặt

Claude Desktop là cách đơn giản nhất và không cần cài Node.js:

Tải file ferry-mcp.mcpb từ bản phát hành mới nhất trên GitHub và mở file.
Nhập API key.
Nếu cần, bật cho phép thao tác ghi.

Claude Code cần Node.js từ 22.12 trở lên; npx tải gói @ferryvn/mcp từ npm khi khởi động:

claude mcp add ferryvn -e FERRY_API_KEY=<key> -- npx -y @ferryvn/mcp

Muốn cho phép thao tác ghi, thêm -e FERRY_MCP_ENABLE_WRITES=true vào lệnh claude mcp add. Nếu đã cài toàn cục bằng npm install -g @ferryvn/mcp, có thể thay npx -y @ferryvn/mcp bằng ferry-mcp. Với các ứng dụng MCP khác, khai báo máy chủ theo cách của ứng dụng đó: lệnh chạy là npx với tham số -y @ferryvn/mcp, biến môi trường là FERRY_API_KEY và tuỳ chọn FERRY_ENV.

Công cụ chỉ đọc và công cụ ghi

Công cụ chỉ đọc luôn có sẵn:

Công cụ	Việc làm
`search_locations`, `list_routes`	Tìm bến (không phân biệt dấu) và xem tuyến cùng hãng tàu
`search_voyages`, `get_voyage_calendar`	Tìm chuyến theo ngày hoặc khoảng ngày; xem số chuyến mỗi ngày
`get_route_prices`, `get_seat_map`	Giá bán của tuyến; ghế trống theo hạng ghế kèm giá và phí bến
`quote_booking`	Kiểm tra booking và báo tổng tiền, không tạo gì
`find_customers`	Tìm khách hàng
`get_booking`, `list_bookings`, `list_cancel_requests`	Đọc booking, danh sách booking và yêu cầu huỷ vé
`get_disruptions`, `get_account`, `list_vouchers`	Thông báo chậm hoặc huỷ chuyến ảnh hưởng booking, số dư và hạn mức, voucher

Công cụ ghi chỉ có khi đặt FERRY_MCP_ENABLE_WRITES=true (đúng chuỗi này):

Công cụ	Tác động
`create_customer`	Tạo khách hàng
`create_booking`	Tạo booking đã kiểm tra, gắn ghế và hành khách, ở trạng thái Requested, chưa thanh toán; không trừ tiền
`request_cancellation`	Giữ ngay phí huỷ và đánh dấu vé đã huỷ tức thì

Mô hình an toàn

Không bao giờ mở: xuất vé, thanh toán, giao dịch, nạp và rút tiền, điều chỉnh số dư hay hạn mức, sổ công nợ, thêm sửa xoá voucher và giá, cùng cài đặt tổ chức, người dùng, API key và webhook. Booking do agent tạo chỉ dừng ở trạng thái chưa thanh toán; xuất vé là việc của con người qua Dashboard, SDK hoặc CLI.
Con người xác nhận mọi thao tác ghi: nếu ứng dụng hỗ trợ hộp thoại xác nhận của MCP, máy chủ hiện hộp thoại mà mô hình không trả lời thay được. Nếu không, mô hình bắt buộc phải truyền user_confirmed: true sau khi đã cho bạn xem chính xác điều sắp xảy ra. Hộp thoại nêu rõ thay đổi: chuyến, ghế, hành khách và tổng tiền; với yêu cầu huỷ là chuyến và những hành khách bị huỷ vé.
Tham số chặt: tham số lạ hoặc viết sai bị từ chối, không bị bỏ qua lặng lẽ, vì bỏ sót quốc tịch sẽ làm đổi loại vé và giá.
Hạn mức ghi: tối đa FERRY_MCP_MAX_WRITES lệnh ghi mỗi tiến trình, mặc định 20, để chặn agent chạy vòng lặp mất kiểm soát.
Nhật ký kiểm toán: mỗi lần thử ghi là một dòng JSON trên stderr, và được nối vào file đặt trong FERRY_MCP_AUDIT_FILE nếu có. Nhật ký chỉ có mã và số lượng, không có thông tin cá nhân của hành khách.
Dữ liệu cá nhân khi đọc: booking chứa họ tên, số giấy tờ, số điện thoại. Hướng dẫn của máy chủ dặn mô hình chỉ chia sẻ cho người có liên quan. Nếu không muốn agent chạm vào dữ liệu này, ẩn công cụ bằng FERRY_MCP_DISABLED_TOOLS, ví dụ list_bookings,find_customers.

Biến môi trường

Biến môi trường	Ý nghĩa
`FERRY_API_KEY`	API key đối tác; bắt buộc trừ khi chỉ tra bến và tuyến
`FERRY_ENV`, `FERRY_BASE_URL`	`production` (mặc định) hoặc `uat`; hoặc địa chỉ cụ thể
`FERRY_MCP_ENABLE_WRITES`	`true` để bật ba công cụ ghi
`FERRY_MCP_MAX_WRITES`	Số lệnh ghi tối đa mỗi tiến trình (mặc định 20)
`FERRY_MCP_AUDIT_FILE`	File nối thêm nhật ký các lần ghi
`FERRY_MCP_DISABLED_TOOLS`	Công cụ cần ẩn, ngăn cách bằng dấu phẩy
`FERRY_MCP_HTTP_HOST`, `FERRY_MCP_HTTP_TOKEN`, `FERRY_MCP_HTTP_ALLOW_WRITES`, `FERRY_MCP_ALLOWED_HOSTS`, `FERRY_MCP_ALLOWED_ORIGINS`	Chỉ dùng cho chế độ HTTP, xem mục sau
`FERRY_LANG`, `FERRY_TIMEOUT_MS`	Tuỳ chọn: ngôn ngữ thông điệp và thời gian chờ

Giá trị không hợp lệ làm máy chủ dừng ngay lúc khởi động kèm thông báo rõ ràng.

Chế độ HTTP

Mặc định máy chủ chạy qua stdio cho một ứng dụng trên cùng máy. Khi cần chạy như một dịch vụ, ferry-mcp --http --port 3333 mở địa chỉ http://127.0.0.1:3333/mcp (kèm GET /healthz để kiểm tra sống). Máy chủ hành động bằng API key của bạn nên chế độ này có các lớp bảo vệ:

Chống DNS rebinding: header Host phải là tên loopback và Origin của trình duyệt phải là địa chỉ loopback. Thêm địa chỉ khác bằng FERRY_MCP_ALLOWED_HOSTS và FERRY_MCP_ALLOWED_ORIGINS.
Token bắt buộc khi có thể truy cập từ ngoài loopback: đặt FERRY_MCP_HTTP_TOKEN (từ 16 ký tự) để mọi yêu cầu phải gửi Authorization: Bearer <token>. Máy chủ từ chối khởi động nếu thiếu token khi bind địa chỉ không phải loopback, hoặc khi cho phép host hay origin không phải loopback (ví dụ sau reverse proxy).
Mặc định chỉ đọc: chế độ HTTP không có hộp thoại xác nhận của ứng dụng, nên công cụ ghi bị bỏ khỏi danh sách ngay cả khi FERRY_MCP_ENABLE_WRITES=true, trừ khi bạn đặt thêm FERRY_MCP_HTTP_ALLOW_WRITES=true.
Giới hạn yêu cầu: chỉ nhận POST, thân yêu cầu tối đa 1 MB.

Repo có sẵn Dockerfile cho chế độ HTTP. Với mạng ngoài mạng riêng, đặt dịch vụ sau TLS.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách làm đúng
Nhờ agent xuất vé hoặc thanh toán	Máy chủ không có công cụ nào làm việc đó	Xuất vé bằng Dashboard, SDK hoặc CLI sau khi người kiểm tra
Bật ghi là agent tự tạo booking	Mỗi lần ghi vẫn cần con người xác nhận	Đọc kỹ nội dung hộp thoại trước khi đồng ý
Mở cổng HTTP ra mạng mà không đặt token	Máy chủ dùng API key của bạn	Đặt `FERRY_MCP_HTTP_TOKEN`, đặt sau TLS
Agent chia sẻ dữ liệu khách hàng thoải mái	Kết quả đọc chứa thông tin cá nhân	Ẩn công cụ đọc bằng `FERRY_MCP_DISABLED_TOOLS` khi không cần
Thử trên UAT là an toàn như sandbox	Xuất vé trên UAT đặt vé thật và trừ tiền thật	Chỉ xuất vé trên chuyến đã thoả thuận với Ferry; xem Môi trường

Tra ở đâu

Chi tiết cấu hình và bản phát hành nằm ở README của gói MCP trên GitHub và trang bản phát hành. Tham chiếu HTTP gốc ở Scalar UI.

Việc cần tra	Nơi tra
Danh sách công cụ và biến môi trường đầy đủ	README gói MCP trên GitHub
File cài cho Claude Desktop	Bản phát hành mới nhất trên GitHub
Route và schema HTTP phía sau mỗi công cụ	Scalar, nhóm `Voyages`, `Bookings`, `Cancel Ticket Requests`

Đọc tiếp

Trang	Khi nào đọc
SDK TypeScript	Gọi API từ code của bạn
CLI `ferry`	Thao tác tay có xác nhận khi xuất vé
Xác thực bằng API key	Hiểu quyền của key mà máy chủ dùng
Luồng đặt vé	Hiểu trạng thái booking mà `create_booking` tạo ra