Claude Desktop

There are two ways to wire Claude Desktop to the worker. Use the OAuth flow if your Claude Desktop is recent enough — it’s a 3-click install with no config file editing and tokens that auto-rotate.

Method	Setup	Auth	Token rotation	Phụ thuộc Node?
OAuth Custom Connector (recommended)	Click → browser → approve	Per-user OAuth (PKCE)	Auto, 1h access + 30d refresh	No
Bearer token via mcp-remote (fallback)	Edit JSON file	Static sn_prod_*	Manual revoke + recreate	Yes (Node 18+)

The worker accepts both formats on /mcp. Pick whichever works on your machine.

Option A — OAuth Custom Connector (recommended)

This uses Dynamic Client Registration behind the scenes: Claude registers itself with the worker once, walks you through GitHub-style “approve this app” flow, then receives a short-lived access token that auto-refreshes.

Setup

1. Open Claude Desktop.
2. Settings → Connectors → Add custom connector.
3. Fill in:
   • Name: SEO Navigator
   • Remote MCP server URL: https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp
   • Leave OAuth Client ID and OAuth Client Secret empty — the worker uses Dynamic Client Registration, so Claude generates them itself.
4. Click Add.
5. Claude opens a browser tab pointing at https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/oauth/authorize?....
6. Sign in with a user account (the master token won’t work here — OAuth requires a real user; create one at /admin/users if needed).
7. Review the requested scope (mcp:full) and click Approve.
8. Browser closes automatically; Claude shows the connector as active.

That’s it. New chats see the connector immediately. Token lifetime:

• Access token: 1 hour. Claude refreshes automatically.
• Refresh token: 30 days, rotated on every use.
• If you let it sit 30+ days, Claude prompts you to re-authorize — same flow, 10 seconds.

Revoke

Two ways:

• From Claude Desktop: Settings → Connectors → SEO Navigator → Remove. Claude calls /oauth/revoke for you.
• From the worker side: open /admin/audit and filter tool=oauth_revoke to see active OAuth sessions per user; revoke from there.

When OAuth doesn’t work

• Claude Desktop older than May 2026 — no Custom Connector UI. Use Option B.
• Your Claude Desktop shows the Add custom connector button but rejects the worker URL — check that https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/.well-known/oauth-protected-resource responds with JSON (it should, hit the URL in a browser).
• You only have the master token, no user accounts — OAuth requires a user identity. Create one at /admin/users first, then approve as that user.

Option B — Bearer token via mcp-remote (fallback)

Use this when Option A isn’t available on your build of Claude Desktop.

Prerequisites

• Node.js 18+ on PATH (node --version should work in a terminal)
• A bearer token from /admin/tokens (format sn_prod_<32 hex>)

Setup

1. Edit claude_desktop_config.json:

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

2. Paste (merge with existing mcpServers if any):

   {
     "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. Replace PASTE_TOKEN_HERE with the token from /admin/tokens.

4. Quit Claude Desktop fully — closing the window is not enough; Claude keeps running in the system tray.

   • Windows: right-click system tray icon → Quit.
   • macOS: Cmd+Q while focused, or right-click Dock icon → Quit.

5. Reopen Claude Desktop. First launch downloads mcp-remote (~10–30 seconds).

Why mcp-remote?

This worker speaks Streamable HTTP (MCP spec 2025-06-18). Older Claude Desktop config doesn’t have a direct field for that — it only knows command (stdio). mcp-remote is a tiny stdio→HTTP bridge that runs locally, forwards JSON-RPC frames to the remote endpoint, and injects your bearer header.

The day Claude Desktop config grows a native streamable-http field, you can swap command/args for a direct URL. The worker doesn’t change.

Verify (either option)

Start a new chat. The 🔌 icon at the bottom should show seo-navigator with at least 31 tools available. Then ask:

List my sites.

Claude calls list_sites and prints what’s in the registry. You’re set.

Troubleshooting

Symptom	Likely cause	Fix
OAuth: browser opens then immediately closes with an error	Worker OAuth endpoints unreachable	Check https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/.well-known/oauth-protected-resource returns JSON
OAuth: “Invalid client” on the approve screen	DCR failed — the worker didn’t register Claude as a client	Try removing the connector and re-adding
OAuth: stuck on login screen	No user accounts on the worker yet	Master-admin needs to create one at /admin/users; OAuth doesn’t accept master token
🔌 shows 0 tools	Token revoked or scope empty	OAuth: revoke + re-add. Bearer: make a fresh token
🔌 shows “Disconnected”	URL wrong or worker offline	Open the admin URL in a browser to confirm the worker responds
Claude says “I don’t have access”	Connector toggled off in this chat	Click 🔌 → toggle seo-navigator on
Tool fails with E_AUTH	Token expired/revoked	OAuth: re-authorize. Bearer: recreate at /admin/tokens
Tool fails with E_SCOPE_DENIED	Token’s allowed_sites or allowed_tools doesn’t include the request	Edit token scope in admin, or re-approve OAuth with broader scope
npx: command not found on Mac (bearer only)	Node not on PATH	Install from nodejs.org, restart Claude Desktop
First startup very slow (bearer only)	mcp-remote downloading	One-time, ~30 seconds

What’s next

• Tokens & scoping — bearer tokens vs OAuth, per-team scopes
• Writing blog posts — first useful prompt to try
• Astro routes via Claude — vibe-code → deploy