# 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](https://github.com/tinovn/tino-connector-mcp).

## Tổng quan

| Mục | Giá trị |
| --- | --- |
| Máy chủ MCP | `https://api.tino.vn/mcp` |
| Giao thức | MCP Streamable HTTP: mỗi `POST` một thông điệp JSON-RPC, trả JSON (không SSE, không phiên); `GET` trả 405 |
| Phiên bản giao thức | `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Xác thực | `Authorization: Bearer <token>`: token OAuth ([Đăng nhập bằng Tino](/docs/oauth)) hoặc [token API cá nhân](/docs/personal-tokens) |
| Metadata cho client (RFC 9728) | `https://api.tino.vn/.well-known/oauth-protected-resource` |
| Tự đăng ký client (RFC 7591) | `POST https://api.tino.vn/oauth/register` (`registration_endpoint` trong `https://api.tino.vn/.well-known/oauth-authorization-server`) |
| Plugin Claude Code | marketplace `tinovn/tino-connector-mcp`, plugin `tino@tinovn` |

## 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](#dang-nhap-va-cap-quyen)).

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`:

```bash
claude plugin marketplace add tinovn/tino-connector-mcp
```

```bash
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**:

```bash
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](#ung-dung-mcp-khac-cursor-vs-code-n8n)).

### 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](/docs/cli-login#dang-ky-ung-dung).
3. Client mở trang đăng nhập Tino (Authorization Code + PKCE, xem [Đăng nhập bằng Tino](/docs/oauth)); khách đồng ý như mục [Đăng nhập và cấp quyền](#dang-nhap-va-cap-quyen).

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](/docs/personal-tokens).
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:

```json
{
  "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](/docs/api)); 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.

| Quyền (nhãn trên trang đồng ý) | Trợ lý làm được |
| --- | --- |
| Xem thông tin tài khoản | Hồ sơ (đã lược giấy tờ, số điện thoại, địa chỉ, thuế, ngân hàng), thông báo |
| Sửa thông tin tài khoản | Đánh dấu thông báo đã đọc |
| Xem dịch vụ, gồm cả thông tin đăng nhập dịch vụ | Danh sách, chi tiết dịch vụ và VPS, tài nguyên, chứng chỉ SSL; **có thể gồm mật khẩu đăng nhập dịch vụ** |
| Quản lý dịch vụ của bạn | Bật, tắt, khởi động lại VPS, đổi hostname, gia hạn, đặt mua chứng chỉ SSL |
| Xem tên miền | Thông tin tên miền, nameserver, khoá chuyển, tự gia hạn |
| Quản lý tên miền của bạn | Đổi nameserver, đặt mua, gia hạn, bật/tắt khoá, chuyển tiếp |
| Xem bản ghi DNS | Đọc vùng và bản ghi DNS |
| Sửa bản ghi DNS | Thêm, sửa, xoá vùng và bản ghi DNS |
| Xem hoá đơn và thanh toán | Hoá đơn, số dư, lịch sử giao dịch |
| Thanh toán, nạp tiền | Thanh toán hoá đơn bằng **số dư tài khoản Tino**, tạo yêu cầu nạp tiền |
| Xem ticket hỗ trợ | Xem ticket |
| Tạo và trả lời ticket | Tạo, trả lời, đóng, mở lại ticket |
| Xem TinoPay: tài khoản nhận tiền, giao dịch, webhook | Thông tin merchant, tài khoản ngân hàng, tài khoản ảo, giao dịch và thống kê, webhook và nhật ký gửi, ứng dụng thông báo, cấu trúc mã thanh toán, tích hợp Sapo và nhật ký đối soát |
| Quản lý TinoPay: tài khoản ảo, webhook, thông báo, tích hợp Sapo | Tạo, bật, tắt, xoá tài khoản ảo; thêm, sửa, xoá webhook, gửi lại webhook; ứng dụng thông báo Telegram, Zalo, Lark; tích hợp Sapo; sửa merchant, cấu trúc mã thanh toán |
| Xem website TinoPage Builder | Tổng quan dịch vụ, danh sách và chi tiết website, trạng thái lượt tạo website, tên miền riêng, liên hệ và đơn hàng |
| Quản lý website TinoPage Builder: tạo, đăng, tên miền riêng | Tạo website bằng AI, đăng, tạm ngưng, xoá website; thêm, kiểm tra DNS, gỡ tên miền riêng |
| Xem website được TinoWAF bảo vệ và nhật ký sự kiện | Tổng quan dịch vụ, website, tên miền và bản ghi DNS cần trỏ, máy chủ gốc, nhật ký và tóm tắt sự kiện, danh sách IP chặn, cho phép |
| Quản lý TinoWAF: website, mức bảo vệ, máy chủ gốc, luật IP | Thêm, xoá website; đổi mức bảo vệ, bật, tắt chống tấn công khẩn cấp; thêm, gỡ tên miền, kiểm tra DNS; sửa máy chủ gốc; chặn, cho phép IP |
| Duy trì truy cập khi bạn không trực tuyến | Giữ kết nối (tự gia hạn access token) |

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](/docs/api#du-lieu-ca-nhan)).
- [Chính sách bảo mật](https://tino.vn/chinh-sach-bao-mat) · [Điều khoản sử dụng](https://tino.vn/dieu-khoan-su-dung-dich-vu).

## 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ố

| Hiện tượng | Cách xử lý |
| --- | --- |
| Claude Code báo cần xác thực (Needs authentication) | Gõ `/mcp`, chọn `tino`, bấm **Authenticate** |
| Kết nối được một thời gian rồi phải đăng nhập lại | Kết nối lại: lâu không dùng thì refresh token hết hạn, hoặc khách đã thu hồi quyền |
| Trang đăng nhập Tino báo ứng dụng không hợp lệ | Gửi ảnh chụp màn hình cho support@tino.vn |
| Ứng dụng MCP khác không đăng nhập được | Ứng dụng phải hỗ trợ OAuth của MCP (tự đăng ký client); không hỗ trợ, hoặc chạy trên máy chủ không mở được trình duyệt, thì dùng token API cá nhân (mục Ứng dụng MCP khác) |
| Tự đăng ký báo `429 too_many_requests` | Mỗi IP đăng ký tối đa 10 lần mỗi giờ: client nên lưu `client_id` đã đăng ký để dùng lại |
| Dùng token cá nhân mà trợ lý không thấy tool cần dùng | Token thiếu quyền đó: tạo token mới đủ quyền |
| Trợ lý báo `insufficient_scope` | Tool không áp dụng cho tài nguyên đó với quyền đã cấp, ví dụ lệnh VPS trên gói hosting |
| HTTP 403 `ip_not_allowed` | Token cá nhân có giới hạn IP, đang gọi từ IP khác |
| Không thấy lệnh huỷ dịch vụ | Đúng thiết kế: huỷ trên bảng điều khiển Tino |

## 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.

```bash
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`).

```bash
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.