Máy chủ MCP

Wink cung cấp hai máy chủ MCP được xác thực. Cả hai đều sử dụng đăng nhập OAuth2 tương tác (luồng mã ủy quyền PKCE) — đại lý AI của bạn mở một tab trình duyệt để bạn đăng nhập bằng tài khoản Wink. Không cần quản lý bí mật khách hàng.

Máy chủ	URL	Chức năng
Inventory API	https://api.wink.travel/mcp	Kho hàng, đặt phòng, giá, kênh bán hàng, phân tích và tất cả các hoạt động trên nền tảng
Integrations	https://integrations.wink.travel/mcp	Tích hợp quản lý kênh — đồng bộ bất động sản, giá và tình trạng với các OTA

---

Cách xác thực hoạt động

Máy chủ MCP của Wink sử dụng luồng OAuth2 Authorization Code + PKCE và hỗ trợ Đăng ký Khách hàng Động (RFC 7591). Đây là những gì xảy ra khi bạn kết nối lần đầu:

1. Khách hàng AI của bạn phát hiện máy chủ ủy quyền từ metadata /.well-known/oauth-protected-resource của điểm cuối MCP.
2. Khách hàng tự đăng ký qua Đăng ký Khách hàng Động — không cần thiết lập ứng dụng thủ công.
3. Khách hàng mở một tab trình duyệt đến https://iam.wink.travel. Bạn đăng nhập bằng tài khoản Wink và chấp thuận các quyền được yêu cầu trên màn hình đồng ý.
4. Wink cấp một token truy cập được phạm vi hóa cho tài khoản của bạn và liên kết với danh tính của bạn.
5. Khách hàng AI đính kèm token vào mọi yêu cầu MCP. Tất cả kết quả công cụ tự động được phạm vi hóa theo thực thể quản lý của bạn.
6. Token hết hạn sau 3 giờ. Khách hàng AI của bạn làm mới token một cách im lặng trong nền mà không yêu cầu đăng nhập lại.

Mọi cuộc gọi công cụ đều chạy dưới danh tính của bạn — các quy tắc ACL bảo vệ cổng web cũng áp dụng cho đại lý AI.

---

Kết nối khách hàng AI của bạn

Claude Code

1. Đảm bảo Claude Code được cập nhật:

   npm install -g @anthropic-ai/claude-code

2. Thêm máy chủ MCP Inventory của Wink:

   claude mcp add wink-inventory https://api.wink.travel/mcp --transport http

3. Claude Code liên hệ với máy chủ, phát hiện máy chủ ủy quyền và mở trình duyệt mặc định của bạn.

4. Đăng nhập vào Wink và chấp thuận yêu cầu quyền trên màn hình đồng ý.

5. Claude Code xác nhận kết nối. Gõ /mcp để kiểm tra máy chủ xuất hiện và các công cụ đã được tải.

Để thêm máy chủ Integrations:

claude mcp add wink-integrations https://integrations.wink.travel/mcp --transport http

Chia sẻ với nhóm của bạn

Thêm --scope project vào lệnh claude mcp add và Claude Code sẽ ghi URL máy chủ vào .mcp.json ở thư mục gốc repo. Cam kết file đó — mỗi thành viên trong nhóm sẽ hoàn thành đăng nhập trình duyệt lần đầu khi kết nối.

Claude Desktop

1. Chỉnh sửa file cấu hình Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Thêm các mục máy chủ MCP:

   claude_desktop_config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Thoát hoàn toàn và khởi động lại Claude Desktop (dùng Quit từ thanh menu — đóng cửa sổ không đủ).

4. Claude Desktop mở một tab trình duyệt cho mỗi máy chủ mới. Đăng nhập vào Wink và chấp thuận quyền.

5. Biểu tượng phích cắm trên thanh công cụ dưới cùng hiển thị cả hai máy chủ đã kết nối.

OpenAI Codex

1. Đảm bảo Codex CLI đã được cài đặt:

   npm install -g @openai/codex

2. Mở (hoặc tạo) file cấu hình Codex:

   • macOS / Linux: ~/.codex/config.json
   • Windows: %USERPROFILE%\.codex\config.json

3. Thêm các mục máy chủ MCP của Wink:

   ~/.codex/config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

4. Khởi động Codex. Lần đầu sử dụng, Codex mở tab trình duyệt đến https://iam.wink.travel.

5. Đăng nhập vào Wink và chấp thuận các quyền được yêu cầu.

6. Codex xác nhận kết nối. Chạy codex và yêu cầu liệt kê các công cụ có sẵn để kiểm tra máy chủ Wink đang hoạt động.

Ghi chú

Hỗ trợ MCP của Codex CLI yêu cầu phiên bản 1.0 trở lên. Chạy codex --version để kiểm tra, và npm install -g @openai/codex để nâng cấp.

ChatGPT

Hỗ trợ máy chủ MCP có trong ứng dụng ChatGPT desktop dành cho người dùng Plus, Pro, Team và Enterprise.

1. Tải và cài đặt ứng dụng ChatGPT desktop nếu bạn chưa có.

2. Mở ứng dụng và nhấp vào biểu tượng hồ sơ của bạn ở góc trên bên phải, sau đó chọn Settings.

3. Vào Connectors (hoặc MCP Servers tùy phiên bản ứng dụng) và nhấp Add.

4. Nhập URL máy chủ Inventory của Wink:

   https://api.wink.travel/mcp

   Sau đó nhấp Connect.

5. ChatGPT mở tab trình duyệt đến https://iam.wink.travel. Đăng nhập vào Wink và chấp thuận quyền.

6. Lặp lại bước 4–5 cho máy chủ Integrations:

   https://integrations.wink.travel/mcp

7. Cả hai máy chủ xuất hiện trong danh sách Connectors của bạn. Bắt đầu một cuộc trò chuyện mới — các công cụ Wink sẽ tự động có sẵn.

Giới hạn ứng dụng web

Máy chủ MCP chỉ có thể cấu hình trong ứng dụng desktop. Giao diện web ChatGPT tại chatgpt.com không hỗ trợ máy chủ MCP tùy chỉnh.

Cursor

1. Mở (hoặc tạo) file cấu hình MCP của Cursor:

   • macOS / Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

2. Thêm các mục máy chủ MCP của Wink:

   ~/.cursor/mcp.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Mở Cursor. Vào Settings → Cursor Settings → MCP và xác nhận cả hai máy chủ hiển thị với chỉ báo trạng thái màu xanh. Nếu hiển thị màu đỏ, nhấp Refresh.

4. Cursor mở tab trình duyệt đến https://iam.wink.travel. Đăng nhập vào Wink và chấp thuận quyền.

5. Mở một cuộc trò chuyện (Ctrl+L / Cmd+L) và yêu cầu Cursor liệt kê các công cụ Wink có sẵn để xác nhận kết nối.

Cấu hình phạm vi dự án

Bạn cũng có thể đặt file mcp.json ở thư mục gốc dự án thay vì trong ~/.cursor/. Cấu hình cấp dự án được ưu tiên và làm cho các máy chủ có sẵn cho mọi thành viên trong nhóm mở dự án trong Cursor.

Windsurf

1. Mở (hoặc tạo) file cấu hình MCP của Windsurf:

   • macOS / Linux: ~/.codeium/windsurf/mcp_config.json
   • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

2. Thêm các mục máy chủ MCP của Wink:

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Khởi động lại hoàn toàn Windsurf (File → Quit, sau đó mở lại).

4. Vào Settings → MCP Servers và xác nhận cả hai máy chủ hiển thị là đã kết nối. Windsurf mở tab trình duyệt đến https://iam.wink.travel khi sử dụng lần đầu.

5. Đăng nhập vào Wink và chấp thuận quyền. Các máy chủ chuyển sang màu xanh trong bảng cài đặt khi đã xác thực.

Ghi chú

Hỗ trợ MCP của Windsurf yêu cầu phiên bản 1.4 trở lên. Kiểm tra qua Help → About Windsurf và cập nhật từ trang Windsurf nếu cần.

Cline (VS Code)

Cline là tiện ích mở rộng VS Code với trình quản lý máy chủ MCP tích hợp. Không cần chỉnh sửa JSON thủ công.

1. Cài đặt Cline từ Marketplace VS Code:

   • Mở VS Code và nhấn Ctrl+Shift+X / Cmd+Shift+X
   • Tìm Cline và nhấp Install

2. Nhấp vào biểu tượng Cline trên thanh Activity Bar (thanh bên trái) để mở bảng Cline.

3. Nhấp vào biểu tượng MCP Servers (biểu tượng phích cắm) trên thanh công cụ Cline, sau đó chọn Edit MCP Settings.

4. VS Code mở file cline_mcp_settings.json. Thêm các mục của Wink:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

5. Lưu file. Cline tự động tải lại và mở tab trình duyệt đến https://iam.wink.travel.

6. Đăng nhập vào Wink và chấp thuận quyền. Cả hai máy chủ hiển thị là đang hoạt động trong bảng MCP Servers.

Phương án thay thế: thêm qua URL

Trong bảng MCP Servers, nhấp Add Server và dán trực tiếp https://api.wink.travel/mcp. Cline tự động điền cấu hình và xử lý xác thực mà không cần chỉnh sửa JSON thủ công.

---

Phạm vi

Khi bạn chấp thuận màn hình đồng ý, bạn sẽ thấy phân tích chi tiết các quyền mà đại lý yêu cầu. Các khách hàng MCP sử dụng cùng từ vựng quyền như phần còn lại của nền tảng — xem đầy đủ tham chiếu phạm vi trên trang Xác thực.

Hai điểm đặc thù với MCP:

• Phạm vi mcp.read mcp.write mcp.remove cũng được yêu cầu để mở kết nối MCP. Khách hàng có phạm vi mcp.* được phép truy cập /mcp, nhưng mọi công cụ được gọi vẫn tuân thủ phạm vi phần của điểm cuối mà nó bao bọc (ví dụ booking.read).
• Khách hàng AI chỉ yêu cầu các phạm vi cần thiết. Bạn có thể từ chối từng quyền trên màn hình đồng ý — các công cụ yêu cầu phạm vi bị từ chối sẽ trả về lỗi khi được gọi.

---

Khắc phục sự cố

Tab trình duyệt không mở

Khách hàng AI của bạn có thể chưa hỗ trợ luồng PKCE tương tác. Xác nhận bạn đang chạy phiên bản mới:

• Claude Code: npm install -g @anthropic-ai/claude-code
• Codex CLI: npm install -g @openai/codex
• Claude Desktop / ChatGPT desktop: cập nhật qua trình cập nhật tích hợp trong ứng dụng

401 Unauthorized sau khi đăng nhập

Token lưu trong bộ nhớ có thể đã hết hạn. Xóa và thêm lại máy chủ để kích hoạt đăng nhập mới:

# Claude Code
claude mcp remove wink-inventory
claude mcp add wink-inventory https://api.wink.travel/mcp --transport http

Với Claude Desktop và ChatGPT, xóa mục máy chủ trong cài đặt, khởi động lại ứng dụng và thêm lại.

403 Forbidden khi gọi một công cụ cụ thể

Công cụ yêu cầu phạm vi bạn không chấp thuận trên màn hình đồng ý. Kết nối lại máy chủ — màn hình đồng ý sẽ xuất hiện lại và bạn có thể chấp thuận quyền còn thiếu.

Máy chủ xuất hiện nhưng cuộc gọi công cụ trả về “account not found”

Bạn đang đăng nhập vào tài khoản Wink không có thực thể quản lý. Truy cập Wink Portal và đảm bảo tài khoản của bạn đã được thiết lập trước khi sử dụng máy chủ MCP.

Token hết hạn giữa phiên làm việc

Token có hiệu lực 3 giờ. Claude Code và Claude Desktop làm mới token im lặng mà không gián đoạn phiên làm việc. Nếu bạn thấy lỗi xác thực sau thời gian không hoạt động dài, gõ một tin nhắn mới — khách hàng sẽ tự động xác thực lại.

Codex CLI báo “MCP server unreachable”

Kiểm tra file ~/.codex/config.json có phải JSON hợp lệ (không có dấu phẩy thừa) và "type": "http" đã được đặt. Codex yêu cầu giao thức HTTP cho máy chủ từ xa; giao thức stdio chỉ dành cho nhị phân cục bộ.

Menu “Connectors” của ChatGPT không hiển thị

Hỗ trợ MCP yêu cầu ứng dụng ChatGPT desktop phiên bản 1.2024.352 trở lên và đăng ký Plus, Pro, Team hoặc Enterprise còn hiệu lực. Cập nhật ứng dụng và kiểm tra gói của bạn trong Settings → Account.

Máy chủ Cursor hiển thị màu đỏ / “Failed to connect”

Xác nhận file ~/.cursor/mcp.json là JSON hợp lệ và chứa "type": "http". Sau đó vào Settings → Cursor Settings → MCP và nhấp Refresh. Nếu lỗi vẫn còn, khởi động lại hoàn toàn Cursor — thay đổi cấu hình không phải lúc nào cũng được nhận diện nếu không khởi động lại.

Máy chủ MCP Windsurf không hiển thị trong cài đặt

Windsurf yêu cầu khởi động lại hoàn toàn (không chỉ tải lại cửa sổ) để nhận thay đổi trong mcp_config.json. Dùng File → Quit và mở lại. Nếu máy chủ vẫn không xuất hiện, xác nhận bạn đang dùng Windsurf 1.4+ qua Help → About Windsurf.

Tùy chọn “Add Server” của Cline không hiển thị

Trình quản lý máy chủ MCP yêu cầu Cline 2.0 trở lên. Mở bảng Extensions của VS Code, tìm Cline và nhấp Update nếu có bản cập nhật. Sau khi cập nhật, tải lại VS Code (Ctrl+Shift+P → “Developer: Reload Window”).

---

Mở Wink Portal Wink trên GitHub