Claude Desktop

Có hai cách để kết nối Claude Desktop với worker. Hãy dùng luồng OAuth nếu Claude Desktop của bạn đủ mới — chỉ 3 click cài đặt, không cần chỉnh file config và token tự xoay vòng.

Phương thức	Setup	Auth	Token rotation	Phụ thuộc Node?
OAuth Custom Connector (khuyến nghị)	Click → browser → approve	OAuth theo user (PKCE)	Tự động, 1h access + 30d refresh	Không
Bearer token qua mcp-remote (fallback)	Sửa file JSON	Static sn_prod_*	Revoke thủ công + tạo lại	Có (Node 18+)

Worker chấp nhận cả hai định dạng trên /mcp. Chọn cái nào hoạt động trên máy bạn.

Cách A — OAuth Custom Connector (khuyến nghị)

Cái này dùng Dynamic Client Registration ở phía sau: Claude tự đăng ký với worker một lần, dẫn bạn qua luồng “approve this app” kiểu GitHub, sau đó nhận một access token ngắn hạn tự refresh.

Setup

1. Mở Claude Desktop.
2. Settings → Connectors → Add custom connector.
3. Điền vào:
   • Name: SEO Navigator
   • Remote MCP server URL: https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp
   • Để trống OAuth Client ID và OAuth Client Secret — worker dùng Dynamic Client Registration, nên Claude sẽ tự sinh chúng.
4. Click Add.
5. Claude mở một tab trình duyệt trỏ tới https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/oauth/authorize?....
6. Đăng nhập bằng tài khoản user (master token sẽ không hoạt động ở đây — OAuth yêu cầu user thực; tạo một tài khoản tại /admin/users nếu cần).
7. Xem lại scope được yêu cầu (mcp:full) và click Approve.
8. Trình duyệt tự đóng; Claude hiển thị connector ở trạng thái active.

Vậy thôi. Chat mới sẽ thấy connector ngay lập tức. Thời hạn token:

• Access token: 1 giờ. Claude tự refresh.
• Refresh token: 30 ngày, xoay vòng mỗi lần dùng.
• Nếu để yên trên 30 ngày, Claude sẽ nhắc bạn re-authorize — vẫn cùng luồng đó, 10 giây.

Revoke

Hai cách:

• Từ Claude Desktop: Settings → Connectors → SEO Navigator → Remove. Claude tự gọi /oauth/revoke cho bạn.
• Từ phía worker: mở /admin/audit và filter tool=oauth_revoke để xem các session OAuth đang hoạt động theo từng user; revoke từ đó.

Khi OAuth không hoạt động

• Claude Desktop cũ hơn tháng 5/2026 — không có UI Custom Connector. Dùng Cách B.
• Claude Desktop của bạn có nút Add custom connector nhưng từ chối URL worker — kiểm tra rằng https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/.well-known/oauth-protected-resource trả về JSON (nó phải trả, mở URL trên trình duyệt để xem).
• Bạn chỉ có master token, không có tài khoản user — OAuth yêu cầu danh tính user. Tạo một tài khoản tại /admin/users trước, sau đó approve dưới tư cách user đó.

Cách B — Bearer token qua mcp-remote (fallback)

Dùng cách này khi Cách A không khả dụng trên bản build Claude Desktop của bạn.

Điều kiện tiên quyết

• Node.js 18+ trên PATH (node --version phải chạy được trong terminal)
• Một bearer token từ /admin/tokens (định dạng sn_prod_<32 hex>)

Setup

1. Sửa claude_desktop_config.json:

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

2. Dán vào (merge với mcpServers đã có nếu có):

   {
     "mcpServers": {
       "seo-navigator": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp",
           "--header",
           "Authorization:Bearer PASTE_TOKEN_HERE"
         ]
       }
     }
   }

3. Thay PASTE_TOKEN_HERE bằng token từ /admin/tokens.

4. Thoát Claude Desktop hoàn toàn — đóng cửa sổ là chưa đủ; Claude vẫn chạy ngầm dưới khay system tray.

   • Windows: click chuột phải vào icon system tray → Quit.
   • macOS: Cmd+Q khi đang focus, hoặc click chuột phải vào icon Dock → Quit.

5. Mở lại Claude Desktop. Lần mở đầu sẽ tải mcp-remote (~10–30 giây).

Tại sao là mcp-remote?

Worker này nói Streamable HTTP (MCP spec 2025-06-18). Config Claude Desktop cũ không có trường trực tiếp cho cái đó — nó chỉ biết command (stdio). mcp-remote là một cây cầu stdio→HTTP nhỏ, chạy local, forward frame JSON-RPC tới endpoint remote, và inject header bearer của bạn.

Đến ngày config Claude Desktop có trường streamable-http native, bạn có thể thay command/args bằng URL trực tiếp. Worker không đổi.

Kiểm tra (cả hai cách)

Mở một chat mới. Biểu tượng 🔌 ở dưới cùng sẽ hiển thị seo-navigator với ít nhất 31 tool khả dụng. Sau đó hỏi:

List my sites.

Claude gọi list_sites và in ra những gì có trong registry. Vậy là xong.

Khắc phục sự cố

Triệu chứng	Nguyên nhân nhiều khả năng	Cách fix
OAuth: trình duyệt mở rồi đóng ngay với lỗi	Các endpoint OAuth của worker không reach được	Kiểm tra https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/.well-known/oauth-protected-resource có trả JSON không
OAuth: “Invalid client” trên màn approve	DCR fail — worker không đăng ký được Claude làm client	Thử xoá connector rồi thêm lại
OAuth: kẹt ở màn login	Worker chưa có tài khoản user nào	Master-admin cần tạo tại /admin/users; OAuth không chấp nhận master token
🔌 hiển thị 0 tool	Token bị revoke hoặc scope rỗng	OAuth: revoke + thêm lại. Bearer: tạo token mới
🔌 hiển thị “Disconnected”	URL sai hoặc worker offline	Mở URL admin trên trình duyệt để xác nhận worker còn phản hồi
Claude nói “I don’t have access”	Connector bị tắt trong chat này	Click 🔌 → bật seo-navigator
Tool fail với E_AUTH	Token hết hạn/bị revoke	OAuth: re-authorize. Bearer: tạo lại tại /admin/tokens
Tool fail với E_SCOPE_DENIED	allowed_sites hoặc allowed_tools của token không bao gồm request	Sửa scope token trong admin, hoặc re-approve OAuth với scope rộng hơn
npx: command not found trên Mac (chỉ bearer)	Node không có trên PATH	Cài từ nodejs.org, khởi động lại Claude Desktop
Lần khởi động đầu rất chậm (chỉ bearer)	mcp-remote đang tải	Một lần duy nhất, ~30 giây

Bước tiếp theo

• Tokens & scoping — bearer token vs OAuth, scope theo team
• Viết bài blog — prompt hữu ích đầu tiên để thử
• Astro routes qua Claude — vibe-code → deploy