Connector claude.ai và ChatGPT

Vị trí trong trang admin: System › Settings › API & AI agents (/agent/keys), tab Connected apps. Màn hình cấp quyền mở tại /agent/consent khi connector yêu cầu quyền truy cập (mục này không có trong menu).

Chức năng

Các ứng dụng AI web không thể đọc key từ ổ đĩa của bạn. Chúng kết nối qua OAuth: bạn thêm URL MCP của panel, ứng dụng sẽ chuyển bạn đến trang admin của chính mình để đăng nhập, bạn chọn những gì ứng dụng được phép thực hiện và trong bao lâu, sau đó ứng dụng sẽ nhận token ngắn hạn. Không cần sao chép hay dán key nào. Bạn có thể ngắt kết nối ứng dụng bất kỳ lúc nào.

Sử dụng tính năng này cho custom connector của claude.ai, connector ở developer mode của ChatGPT và bất kỳ MCP client nào khác hỗ trợ OAuth với dynamic client registration. Các công cụ dòng lệnh cũng có thể dùng quy trình này, nhưng admin API key sẽ đơn giản hơn đối với chúng.

Yêu cầu

Hạng mục	Yêu cầu
URL	https://cloud.example.com/mcp/admin, có thể truy cập từ internet (các máy chủ của nhà cung cấp sẽ kết nối tới URL này).
Reverse proxy	Nếu bạn đặt proxy riêng phía trước panel, proxy phải chuyển tiếp các đường dẫn /mcp/admin, /oauth-admin/ và /.well-known/ tới panel.
Bạn	Đã đăng nhập vào admin NexCMP trên cùng trình duyệt mà bạn dùng cho màn hình cấp quyền.
Client	Hỗ trợ MCP qua Streamable HTTP, OAuth 2.1 với PKCE (S256) và dynamic client registration.

Kết nối

1. Trong ứng dụng AI, thêm một custom MCP connector và dán https://cloud.example.com/mcp/admin. Trong claude.ai, mục này nằm trong cài đặt connectors (add custom connector); trong ChatGPT, mục này nằm trong developer mode (add an MCP connector, authentication OAuth).
2. Chọn Sign in (hoặc "Connect") trong ứng dụng. Trình duyệt của bạn sẽ mở màn hình cấp quyền của admin NexCMP. Nếu chưa đăng nhập, hãy đăng nhập trước; màn hình sẽ tiếp tục sau đó.
3. Đọc thông tin: "Example AI app wants to manage this NexCMP admin" (tên của ứng dụng đang yêu cầu), cùng địa chỉ mà bạn sẽ được chuyển hướng trở lại.
4. Đánh dấu chọn các scope cần cấp. Các scope mà ứng dụng yêu cầu đã được chọn sẵn; nếu ứng dụng không yêu cầu gì, chỉ có admin:read được chọn. Xem Scopes.
5. Chọn thời hạn kết nối: 7, 30 hoặc 90 ngày (mặc định là 30).
6. Nhấp vào Allow. Trình duyệt quay trở lại ứng dụng, hiện đã được kết nối. Nhấp vào Deny để từ chối.

::: important Chọn scope tương tự như khi tạo key Chỉ cấp bộ quyền tối thiểu vừa đủ cho nhu cầu. Các thao tác về tiền bạc, xóa và bảo mật vẫn sẽ dừng lại ở bước xem trước và cần bạn phê duyệt, nhưng một kết nối có settings:write vẫn có thể thay đổi thương hiệu và email của bạn. :::

Quản lý và thu hồi

Mở System › Settings › API & AI agents › Connected apps. Bảng sẽ liệt kê mọi ứng dụng bạn đã kết nối: ứng dụng, scope, thời điểm kết nối, thời điểm hết hạn và lần sử dụng gần nhất.

Để ngắt kết nối một ứng dụng, hãy nhấp vào Revoke và xác nhận. Token của ứng dụng sẽ ngừng hoạt động ngay lập tức; ứng dụng phải đi qua màn hình cấp quyền lần nữa để kết nối lại.

Quy trình hoạt động

Bước	Chi tiết
Discovery	Ứng dụng đọc /.well-known/oauth-protected-resource/mcp/admin rồi đến /.well-known/oauth-authorization-server/oauth-admin. Issuer là https://cloud.example.com/oauth-admin.
Đăng ký	Ứng dụng tự đăng ký (POST /oauth-admin/register, RFC 7591). Chỉ hỗ trợ public client (không có client secret). Địa chỉ redirect phải là https, hoặc http trên cùng máy tính (loopback).
Cấp quyền	GET /oauth-admin/authorize với phương thức PKCE S256. Tham số resource, khi được gửi, phải là URL /mcp/admin của bảng điều khiển này. Yêu cầu có hiệu lực trong 10 phút và được gắn với trình duyệt đã khởi tạo nó.
Chấp thuận	Bạn chọn các scope và thời hạn (ở trên). Authorization code có hiệu lực trong 60 giây và chỉ sử dụng được một lần.
Token	POST /oauth-admin/token trả về một access token (khóa ak_o..., có hiệu lực 1 giờ hoặc cho đến khi kết thúc kết nối, tùy điều kiện nào đến trước) và một refresh token (akr_...). Mỗi lần làm mới sẽ trả về một refresh token mới; token cũ sẽ ngừng hoạt động. Kết nối sẽ kết thúc sau số ngày bạn đã chọn.
Thu hồi	Revoke trong Connected apps, hoặc ứng dụng gọi POST /oauth-admin/revoke (RFC 7009).

Access token hoạt động như một admin key với các scope bạn đã cấp: cùng quy tắc scope, xác nhận, rate limit và nhật ký hoạt động. Các lệnh gọi của token sẽ hiển thị trên tab Activity.

Kiểm tra

1. Trong ứng dụng, hãy hỏi "run system_health" (hoặc "what tools do you have?"). Ứng dụng sẽ liệt kê các công cụ mà scope của bạn cho phép (danh sách công cụ).
2. Mở Connected apps: Last used thay đổi.
3. Mở Activity: các lệnh gọi được liệt kê cùng tên ứng dụng và mcp.

Hạn mức & lưu ý

• Nếu ứng dụng yêu cầu đăng nhập lại sau một giờ, điều này là bình thường khi client không tự làm mới; hãy kết nối lại.
• Refresh token bị sử dụng hai lần sẽ bị coi là đã bị đánh cắp: toàn bộ kết nối sẽ bị thu hồi. Hãy kết nối lại từ ứng dụng.
• Authorization code bị sử dụng hai lần sẽ bị từ chối (invalid_grant) và các token đã phát hành từ mã này sẽ bị thu hồi.
• Quyền truy cập OAuth không bao giờ vượt quá các quy tắc scope cho phép: những điều khóa không bao giờ có thể làm cũng áp dụng cho các ứng dụng đã kết nối.
• Các nhà cung cấp có thể thay đổi menu và tính năng hỗ trợ. Nếu ứng dụng của nhà cung cấp không hỗ trợ custom connector trên gói của bạn, hãy sử dụng admin API key với ứng dụng desktop hoặc dòng lệnh để thay thế.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
Màn hình chấp thuận thông báo "Wrong browser"	Yêu cầu đã được khởi tạo trong trình duyệt khác với trình duyệt bạn đang đăng nhập	Bắt đầu lại kết nối từ ứng dụng AI trên cùng trình duyệt đó.
Màn hình chấp thuận thông báo yêu cầu đã hết hạn hoặc không tồn tại	Đã quá 10 phút, hoặc liên kết đã bị mở hai lần	Bắt đầu lại kết nối từ ứng dụng AI.
Trang "Unknown client" hoặc "redirect address does not match"	Bản đăng ký của ứng dụng đã cũ, hoặc ứng dụng sử dụng địa chỉ redirect chưa từng đăng ký	Xóa connector trong ứng dụng rồi thêm lại.
invalid_target	resource được gửi không phải là URL /mcp/admin của bảng điều khiển này	Sử dụng chính xác URL hiển thị trên tab Connect an AI.
invalid_request về PKCE	Client không gửi code_challenge_method=S256	Sử dụng client có hỗ trợ OAuth 2.1 cùng PKCE.
Ứng dụng kết nối được nhưng một lệnh gọi trả về insufficient_scope	Bạn chưa tick chọn scope đó	Thu hồi kết nối và kết nối lại với scope đã được tích chọn.
Ứng dụng không thể truy cập URL	DNS, TLS hoặc reverse proxy chặn /mcp/admin, /oauth-admin/ hoặc /.well-known/	Kiểm tra lại các quy tắc proxy.