# Kết nối

Địa chỉ máy chủ MCP:

```text
https://mcp-pos.pancake.biz/mcp
```

## 1. Lấy API key

Nên dùng **API key tài khoản**: AI chỉ làm được những gì chính bạn được phép trong từng cửa hàng.

1. Mở trang **Tài khoản** trên Pancake POS, mục **API Key**, bấm **Tạo mới**.
2. Đặt tên dễ nhớ, ví dụ "Claude".
3. Sao chép key ngay: key chỉ hiện một lần.

Cũng dùng được API key cửa hàng (**Cấu hình › Ứng dụng › Webhook/API**, tab **API Key**), nhưng key này có toàn quyền trên cửa hàng. So sánh hai loại: [Xác thực](/developers/api/authentication).

## 2. Thêm vào client

### Claude Desktop

1. Mở **Settings › Connectors › Add custom connector**.
2. Dán `https://mcp-pos.pancake.biz/mcp` vào ô URL, đặt tên (ví dụ "Pancake POS"), bấm **Add**.
3. Claude mở trình duyệt tới trang xác nhận của Pancake POS MCP. Dán API key, bấm **Authorize**. Trình duyệt tự đóng khi xong.

Claude Desktop bản cũ chưa có mục Connectors: mở **Settings › Developer › Edit Config** và thêm đoạn dưới (cần cài Node.js vì dùng `mcp-remote` làm cầu nối):

```json
{
  "mcpServers": {
    "pancake-pos": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.18", "https://mcp-pos.pancake.biz/mcp", "--header", "X-Api-Key:API_KEY"]
    }
  }
}
```

Lưu file, thoát hẳn Claude Desktop (macOS: `Cmd+Q`, không chỉ đóng cửa sổ) rồi mở lại.

### Claude Code

```bash
claude mcp add --transport http -s user pancake-pos https://mcp-pos.pancake.biz/mcp --header "X-Api-Key: API_KEY"
```

Kiểm tra bằng `claude mcp list` (thấy `pancake-pos … ✓ Connected`). Trong phiên làm việc, gõ `/mcp` để xem các tool `pos_*`.

### Codex

Thêm vào `~/.codex/config.toml` (dùng chung cho Codex app, extension IDE và CLI):

```toml
[mcp_servers.pancake-pos]
url = "https://mcp-pos.pancake.biz/mcp"
http_headers = { "X-Api-Key" = "API_KEY" }
```

Codex dùng `http_headers`, khác tên trường `headers` của client khác.

### Cursor

Thêm vào `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pancake-pos": {
      "url": "https://mcp-pos.pancake.biz/mcp",
      "headers": { "X-Api-Key": "API_KEY" }
    }
  }
}
```

### Client khác

Client hỗ trợ MCP qua HTTP (Streamable HTTP) đều kết nối được:

- URL: `https://mcp-pos.pancake.biz/mcp`
- Xác thực: header `X-Api-Key: API_KEY` (hoặc `Authorization: Bearer API_KEY`), hoặc OAuth nếu client hỗ trợ (client tự mở trang xác nhận để bạn dán key).

## 3. Thử ngay

Mở cuộc trò chuyện mới và gõ:

- "Liệt kê 5 đơn hàng gần nhất"
- "Doanh thu hôm nay bao nhiêu?"
- "Sản phẩm nào sắp hết hàng?"

Lần đầu, client hỏi có cho phép gọi tool không: chọn **Allow**. Thấy danh sách đơn hàng là đã kết nối xong.

Tài khoản có nhiều cửa hàng: nói rõ cửa hàng nào trong câu hỏi, hoặc hỏi "Tôi có những cửa hàng nào?" trước.

## Xử lý sự cố

| Hiện tượng | Cách xử lý |
|---|---|
| Không thấy tool `pos_*` | Thoát hẳn rồi mở lại client; kiểm tra URL có đuôi `/mcp` |
| Trang xác nhận báo API key không hợp lệ | Sao chép lại key đầy đủ; key đã bị thu hồi thì tạo key mới |
| AI báo không đủ quyền | Key tài khoản theo quyền của bạn trong cửa hàng; nhờ quản trị viên cấp thêm quyền |
| `npx` không chạy (Claude Desktop bản cũ) | Cài Node.js 18 trở lên |
| Codex không kết nối | Kiểm tra dùng `http_headers`, không phải `headers` |

Cần hỗ trợ cài đặt: liên hệ đội ngũ Pancake.