Kết nối Claude, ChatGPT với Tino (MCP)

Tino Connector cho trợ lý AI (Claude, ChatGPT, ứng dụng MCP khác) làm việc với tài khoản Tino: xem và quản lý dịch vụ hosting, VPS, tên miền, bản ghi DNS, hoá đơn và ticket bằng câu lệnh thường, chỉ trong phạm vi quyền khách đồng ý. Kết nối dùng chuẩn MCP (Model Context Protocol) và đăng nhập OAuth: trợ lý không bao giờ thấy mật khẩu hay mã OTP của khách.

Cập nhật: 2026-10-27. Mã nguồn máy chủ MCP: kho công khai tinovn/tino-connector-mcp.

Tổng quan

Kết nối

Claude (web, Desktop, điện thoại)

1. Mở Claude, vào Customize → Connectors, bấm Add custom connector.
2. Tên: Tino; URL: https://api.tino.vn/mcp.
3. Phần xác thực để mặc định (đăng nhập OAuth); không cần nhập client ID hay header.
4. Bấm Connect: trang đăng nhập Tino mở ra (mục Đăng nhập và cấp quyền).

Tuỳ gói Claude, quản trị viên của tổ chức có thể phải bật connector trước.

Claude Code

Cài plugin tino:

claude plugin marketplace add tinovn/tino-connector-mcp

claude plugin install tino@tinovn

Trong Claude Code gõ /mcp, chọn tino, bấm Authenticate. Không dùng plugin thì thêm thẳng máy chủ MCP rồi cũng /mcp → Authenticate:

claude mcp add --transport http tino https://api.tino.vn/mcp

Claude Code không tự đăng ký client: nó nhận diện bằng Client ID Metadata Document (client_id=https://claude.ai/oauth/claude-code-client-metadata). Mặc định Claude Code xin đủ các quyền máy chủ MCP liệt kê, gồm cả quyền ghi; muốn quyền hẹp hơn thì dùng token API cá nhân (mục Ứng dụng MCP khác).

ChatGPT

Tài khoản ChatGPT bật chế độ nhà phát triển (Developer mode) thêm được connector MCP tuỳ chỉnh: URL https://api.tino.vn/mcp, xác thực OAuth. Đường bấm cụ thể tuỳ phiên bản giao diện ChatGPT.

Ứng dụng MCP khác (Cursor, VS Code, n8n…)

Cách chính: đăng nhập OAuth. Client MCP hỗ trợ OAuth theo đặc tả MCP tự đăng ký với Tino rồi mở trang đăng nhập; chỉ cần khai URL https://api.tino.vn/mcp, không cần client ID, khoá bí mật hay header:

1. Gọi https://api.tino.vn/mcp khi chưa có token thì nhận HTTP 401; header WWW-Authenticate chỉ tới metadata https://api.tino.vn/.well-known/oauth-protected-resource.
2. Client đọc discovery https://api.tino.vn/.well-known/oauth-authorization-server và tự đăng ký qua registration_endpoint (POST https://api.tino.vn/oauth/register, RFC 7591): client công khai (token_endpoint_auth_method: none), redirect về http://localhost hoặc 127.0.0.1 (mọi cổng) hay https://. Quy tắc từng trường ở Đăng nhập từ CLI.
3. Client mở trang đăng nhập Tino (Authorization Code + PKCE, xem Đăng nhập bằng Tino); khách đồng ý như mục Đăng nhập và cấp quyền.

Trên trang Ứng dụng được cấp quyền, ứng dụng tự đăng ký hiện bằng tên nó khai (client_name).

Cách thay thế: token API cá nhân. Dùng khi ứng dụng không hỗ trợ OAuth của MCP, chạy trên máy chủ không mở được trình duyệt, hoặc cần quyền hẹp hơn, giới hạn IP:

1. Tạo token ở https://auth.tino.vn/me/security, mục Token API: chọn đúng quyền cần dùng; ứng dụng chạy trên máy chủ cố định thì nên giới hạn IP. Xem Token API cá nhân.
2. Khai máy chủ MCP trong ứng dụng: URL https://api.tino.vn/mcp, header Authorization: Bearer <token>. Dạng cấu hình JSON phổ biến:

{
  "mcpServers": {
    "tino": {
      "type": "http",
      "url": "https://api.tino.vn/mcp",
      "headers": { "Authorization": "Bearer tinopat_…" }
    }
  }
}

Token là chìa khoá tài khoản: không dán vào khung chat, không commit lên Git; lộ thì thu hồi ngay ở trang Token API.

Đăng nhập và cấp quyền

Khi kết nối, trình duyệt mở trang Tino: khách đăng nhập như thường (mã OTP qua email hoặc số điện thoại, Google, Zalo hoặc passkey), xem danh sách quyền ứng dụng xin rồi bấm Đồng ý. Ứng dụng nhận access token có hạn (mặc định 24 giờ) và refresh token để tự gia hạn; refresh token không dùng quá hạn (mặc định 30 ngày) thì phải kết nối lại.

Đồng ý là cấp toàn bộ quyền trong danh sách. Muốn quyền hẹp hơn, dùng token API cá nhân chỉ với các quyền cần thiết.

Quyền và tool

Mỗi tool là một route của gateway /v1 (xem Gọi API Tino); mô tả tool kết thúc bằng route và quyền, ví dụ GET /details · scope profile:read. tools/list chỉ trả các tool token gọi được, nên trợ lý không thấy tool ngoài quyền đã cấp.

Tool có quyền đọc mang chú thích readOnlyHint: true; tool có quyền ghi mang destructiveHint: true. Tool chuyển tiếp email, chuyển hướng tên miền, đăng ký nameserver riêng và lấy nội dung thanh toán của cổng thanh toán mang thêm openWorldHint: true (tác động ra hệ thống bên ngoài).

Không làm được qua MCP

• Huỷ dịch vụ: chỉ làm trên bảng điều khiển khách hàng Tino; MCP không có tool huỷ, kể cả khi token có quyền quản lý dịch vụ.
• Lấy mã chuyển tên miền (EPP), đổi chủ thể tên miền: không bao giờ cấp cho Claude, ChatGPT hay ứng dụng OAuth nào. Chỉ token API cá nhân chọn quyền domains:owner (bắt buộc giới hạn IP) mới có hai tool này; chỉ chọn quyền đó khi thật cần.
• Tạo API token TinoPay, liên kết tài khoản ngân hàng nhận tiền: cũng vậy, chỉ token API cá nhân chọn quyền tinopay:owner (bắt buộc giới hạn IP) mới có các tool này.
• Đặt mua hosting, VPS mới: chưa hỗ trợ. Đặt mua tên miền và chứng chỉ SSL thì được.

Ví dụ câu lệnh

• "Liệt kê dịch vụ Tino của tôi và ngày gia hạn."
• "Tên miền example.vn đang dùng nameserver nào?"
• "Thêm bản ghi A www trỏ về 203.0.113.10 cho example.vn."
• "Tôi còn hoá đơn nào chưa thanh toán?"
• "Khởi động lại VPS có hostname web01." (thao tác ghi: trợ lý nên hỏi xác nhận trước)

An toàn và dữ liệu

• Mọi thao tác thay đổi (đặt hàng, gia hạn, thanh toán, đổi DNS hoặc nameserver, khởi động lại VPS) được đánh dấu là thao tác ghi; máy chủ MCP cũng dặn trợ lý nêu rõ việc sẽ làm và chờ khách đồng ý. Bước hỏi xác nhận do Claude, ChatGPT làm theo cài đặt của ứng dụng: nên giữ chế độ hỏi trước khi chạy và đọc kỹ nội dung trước khi đồng ý.
• Trợ lý chỉ đọc, ghi qua API của Tino trong phạm vi quyền đã cấp; kết quả gửi về Claude hoặc ChatGPT để trả lời khách.
• Máy chủ MCP lọc các trường định danh khỏi mọi bản ghi người (đối tượng có email kèm firstname, lastname hoặc name: tài khoản, liên hệ, chủ thể tên miền) trước khi gửi cho trợ lý: số giấy tờ, ngày sinh, giới tính, số điện thoại, địa chỉ, mã số thuế, mã hộ kinh doanh, ngân hàng, liên kết Zalo, IP và lần đăng nhập. Gọi thẳng gateway /v1 thì câu trả lời giữ nguyên (xem Gọi API Tino).
• Chính sách bảo mật · Điều khoản sử dụng.

Thu hồi quyền

Khách vào https://auth.tino.vn/me/apps (Ứng dụng được cấp quyền), bấm Thu hồi ở "Claude", "Claude Code", "ChatGPT" hoặc tên ứng dụng MCP đã tự đăng ký: mọi token của ứng dụng đó hết hiệu lực ngay. Token API cá nhân thu hồi ở https://auth.tino.vn/me/security, mục Token API.

Xử lý sự cố

Cho nhà phát triển client MCP

Gọi thử bằng token API cá nhân ($TINO_TOKEN). Mỗi thông điệp là một POST JSON-RPC 2.0; không token hoặc token sai thì HTTP 401 kèm header WWW-Authenticate: Bearer error="invalid_token", scope="…", resource_metadata="https://api.tino.vn/.well-known/oauth-protected-resource" để client bắt đầu OAuth.

curl -X POST https://api.tino.vn/mcp \
  -H "Authorization: Bearer $TINO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Gọi một tool: tham số đường dẫn của route là đối số bắt buộc; đối số khác đi vào query (GET, DELETE) hoặc body (POST, PUT).

curl -X POST https://api.tino.vn/mcp \
  -H "Authorization: Bearer $TINO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "service_details", "arguments": {"id": "100001"}}}'

• Phương thức hỗ trợ: initialize, ping, tools/list, tools/call; thông điệp không có id (notification) nhận HTTP 202.
• Kết quả tools/call là câu trả lời của route: JSON dạng text, isError: true khi route báo lỗi (HTTP 4xx, 5xx hoặc có trường error); file (ví dụ PDF hoá đơn) trả dạng resource nhúng base64.
• Tên tool viết thường nối gạch dưới (get_details, service_details, dns_add_record…) và có thể đổi khi API thêm route; lấy danh sách bằng tools/list thay vì ghi cứng.