Tokens & scoping

Endpoint MCP chấp nhận hai kiểu auth. Cả hai đều kết thúc ở cùng một bước kiểm tra scope trên server — khác biệt chỉ nằm ở cách Claude lấy bearer.

OAuth tokens (ưu tiên)

Phát hành bởi luồng OAuth Custom Connector. Chỉ lưu trong Claude Desktop; worker chỉ giữ một hash kèm metadata xoay vòng. Định dạng: oat_<random>.

Thuộc tính	Giá trị
Lifetime	Access token 1 h, refresh token 30 d, xoay vòng mỗi lần refresh
Scope được cấp	Luôn là mcp:full — toàn bộ bề mặt hiển thị với user
Scope theo site	Bị giới hạn bởi whitelist user_sites của user (phía DB, không nằm trong token)
Ràng buộc user	Liên kết với một tài khoản user thực (oauth_access_tokens.user_id)
Chiến lược refresh	Tự động — Claude refresh ngầm
Revoke	Click Remove trong Claude → gọi /oauth/revoke. Hoặc master-admin có thể xoá row trong bảng oauth_access_tokens
Audit trail	Mỗi tools/call ghi actor_user_id từ access token

Lấy một cái: Thêm SEO Navigator làm Custom Connector trong Claude Desktop — xem Bắt đầu nhanh.

Bearer tokens (legacy / fallback)

Chuỗi tĩnh dạng plaintext, mint trong admin dashboard. Định dạng: sn_prod_<32 hex>. Dùng bởi cầu nối mcp-remote khi OAuth không phải là phương án, hoặc cho workflow CLI/CI.

Thuộc tính	Giá trị
Lifetime	Không có (sống tới khi bị revoke)
Scope được cấp	Mảng allowed_sites + allowed_tools rõ ràng theo từng token
Scope theo site	Bất kỳ thứ gì người tạo tick khi mint
Ràng buộc user	tokens.owner_user_id — NULL nghĩa là super-admin phát hành
Chiến lược refresh	Không có — tạo lại thủ công
Revoke	/admin/tokens → nút Revoke màu đỏ
Audit trail	actor_user_id lấy từ tokens.owner_user_id

Mint một bearer token

1. Mở /admin/tokens và click + Create token.
2. Name: mô tả (ví dụ “CI runner”, “blog writer staging”).
3. Allowed sites:
   • Super-admin: chọn site cụ thể hoặc * cho tất cả.
   • User thường: chỉ những site của riêng bạn được liệt kê. Chọn * để mở rộng ra mọi thứ bạn sở hữu tại thời điểm này (cố định khi tạo — các grant sau đó không nới rộng token).
4. Allowed tools:
   • Quick-pick Select all tick mọi built-in + proxy tool an toàn.
   • Quick-pick All except destructive lọc các proxy delete-*, publish-* tool.
   • Quick-pick Built-in only bỏ qua bề mặt proxy wp-mcp-adapter.
   • Các tool chỉ super-admin (ví dụ delete_astro_route) bị ẩn hoàn toàn khỏi user thường.
5. Create. Copy plaintext — nó chỉ hiển thị một lần.

Nếu bạn mất plaintext, revoke và tạo cái mới. Worker chỉ lưu SHA-256 của byte.

OAuth vs bearer — khi nào chọn cái nào

Trường hợp	Chọn
Claude Desktop trên laptop cá nhân	OAuth
Claude Desktop trên máy của đồng nghiệp — dễ bàn giao	OAuth (token theo user, không chia sẻ)
Claude Desktop cũ không có UI Custom Connector	Bearer + mcp-remote
CI runner post lên MCP từ CLI	Bearer (sống lâu, không cần trình duyệt)
Test fixture hoặc khám phá bằng curl	Bearer
Multi-tenant ops nơi mỗi team có user riêng	OAuth (audit gọn hơn)

Bạn có thể có CẢ HAI trên cùng worker, cho cùng một user — OAuth token hoạt động trên user_sites của user, còn bearer token mint scope mà user chọn rõ ràng. Mỗi loại để lại audit trail riêng.

Scope theo site và user_sites

Site KHÔNG bị ghim vào bearer token chỉ bằng ID — chúng được filter dựa trên whitelist user_sites của user đang gọi, ở mỗi request:

• OAuth: token có user_id. Tool call giao site của user đó với site_id được yêu cầu. Ngoài scope → 403 E_SCOPE_DENIED.
• Bearer: token có allowed_sites tường minh. Nếu owner là user thường, worker giao thêm với user_sites hiện tại của họ. Nên việc bỏ một site khỏi grant của user cũng khoá luôn các bearer token của họ.

Nghĩa là super-admin có thể revoke quyền truy cập của một user bằng cách bỏ grant site trong /admin/users — không cần revoke từng token riêng.

Quy tắc bắt buộc

Không token nào, ở cả hai loại, có thể publish ngay hoặc xoá một bài WordPress / Duda. Bước kiểm tra diễn ra ở tầng đăng ký tool — những tool đó đơn giản là không tồn tại trên server. Một token với allowed_tools: ["*"] vẫn không thể gọi delete_post vì không có delete_post để gọi.

Ngoại lệ duy nhất có ghi chép — delete_astro_route — chỉ super-admin gọi được lúc runtime, bất kể giá trị allowed_tools của token là gì.

Audit trail

Mỗi tool call thành công hay thất bại đều ghi một row vào audit_log:

ts            INTEGER   -- unix ms
actor_user_id TEXT      -- từ OAuth user_id hoặc token owner_user_id
token_id      TEXT
site_id       TEXT
tool          TEXT
status        TEXT      -- ok | denied | error
duration_ms   INTEGER
args_json     TEXT      -- cắt còn 1KB
error         TEXT      -- khi status != ok
via           TEXT      -- "default" | "wp-mcp-adapter"

Duyệt và filter tại /admin/audit. User thường chỉ thấy row của chính mình; super-admin thấy mọi thứ.