Claude Code

Claude Code talks to remote MCP servers natively over Streamable HTTP — so unlike Claude Desktop, you don’t need the mcp-remote bridge or Node.js. One claude mcp add command and you’re wired.

The worker accepts both auth styles on /mcp. Use OAuth unless you need a static token for a CI/headless runner.

Method	Setup	Auth	Token rotation
OAuth (recommended)	claude mcp add → /mcp → Authenticate	Per-user OAuth (PKCE)	Auto, refreshed silently
Bearer token (--header)	claude mcp add with --header	Static sn_prod_*	Manual revoke + recreate

The endpoint is the same as Claude Desktop’s:

https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp

Pick a scope first

claude mcp add writes the server to one of three scopes — decide where it should live before running it:

Scope	Flag	Stored in	Use it for
User	--scope user	~/.claude.json (global)	Your own machine — available in every project. Best default for personal use.
Project	--scope project	.mcp.json in the repo root	A team repo — commit it so teammates get the server (each still authenticates as themselves).
Local	--scope local (default)	~/.claude.json, this project only	A quick, project-private setup you don’t want to share.

Examples below use --scope user. Swap in --scope project for a shared repo.

Option A — OAuth (recommended)

OAuth uses Dynamic Client Registration

• PKCE: Claude Code registers itself with the worker, walks you through an “approve this app” browser flow, and receives a short-lived token it refreshes automatically.

Setup

1. Add the server (no credentials yet):

   claude mcp add --transport http --scope user seo-navigator https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp

2. Authenticate. Either start a session and use the menu:

   claude

   then inside the TUI:

   /mcp

   Select seo-navigator (it shows ! Needs authentication), press Enter, and choose Authenticate.

   Or, on Claude Code v2.1.186+, do it straight from the shell:

   claude mcp login seo-navigator

3. Your browser opens the worker’s authorize page. Sign in with a real user account — the master token won’t work here; OAuth requires a user identity. Create one at /admin/users if needed.

4. Review the scope (mcp:full) and click Approve.

5. Back in Claude Code the status flips to ✓ Connected.

Token lifetime: access token ~1 hour (refreshed silently), refresh token 30 days. If it sits unused past 30 days, re-run the /mcp → Authenticate flow (10 seconds).

Note

If the browser doesn’t open, copy the printed URL manually. If the redirect back fails after you approve, paste the full callback URL from your address bar into the Claude Code prompt.

Revoke / re-authenticate

• In a session: /mcp → seo-navigator → Clear authentication.
• From the shell (v2.1.186+): claude mcp logout seo-navigator.
• Worker side: filter /admin/audit by tool=oauth_revoke.

Option B — Bearer token (--header)

Use this for CI/headless runners, or when you’d rather pin a static scoped token than do a browser flow.

Prerequisites

• A bearer token from /admin/tokens (format sn_prod_<32 hex>). See Tokens & scoping for minting and scope.

Setup

claude mcp add --transport http --scope user seo-navigator \
  https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp \
  --header "Authorization: Bearer sn_prod_PASTE_TOKEN_HERE"

The whole header is one quoted argument — "Authorization: Bearer <token>".

Windows PowerShell quoting

PowerShell mangles the inner spaces/colon. Wrap the header in single quotes:

claude mcp add --transport http --scope user seo-navigator `
  https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp `
  --header 'Authorization: Bearer sn_prod_PASTE_TOKEN_HERE'

Or edit .mcp.json directly (project scope)

To check the server into a team repo, add it to .mcp.json at the repo root:

{
  "mcpServers": {
    "seo-navigator": {
      "type": "http",
      "url": "https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SN_TOKEN}"
      }
    }
  }
}

${SN_TOKEN} expands from the environment at connect time — so you commit the config without committing the secret. The first time Claude Code sees a project-scoped server it asks you to approve it (a security check); approve in the prompt or via /mcp.

Verify

claude mcp list

seo-navigator should show ✓ Connected. Then in a session ask:

List my sites.

Claude calls list_sites and prints the registry. You’re set — at least 31 tools are now available.

Managing the server

Command	Does
claude mcp list	All servers + connection status
claude mcp get seo-navigator	Config + status + errors for one server
claude mcp remove seo-navigator	Remove it (add --scope <scope> if defined in several)
/mcp (in a session)	Authenticate, re-authenticate, or inspect tools
claude mcp reset-project-choices	Re-prompt approval for .mcp.json servers you previously rejected

Troubleshooting

Symptom	Likely cause	Fix
claude mcp list shows ! Needs authentication	OAuth not completed	Run /mcp → Authenticate (or claude mcp login seo-navigator)
✗ Failed to connect	URL wrong or worker offline	Open the /mcp URL in a browser to confirm the worker responds
! Connected · tools fetch failed	Connected but tool list errored	claude mcp get seo-navigator for details; re-authenticate
OAuth stuck on login screen	No user accounts on the worker	Master-admin creates one at /admin/users; OAuth won’t accept the master token
Browser opens then errors out	Worker OAuth endpoints unreachable	Check …workers.dev/.well-known/oauth-protected-resource returns JSON
Bearer: tool fails with E_AUTH	Token expired/revoked	Recreate at /admin/tokens, re-run claude mcp add
Tool fails with E_SCOPE_DENIED	Token/user scope excludes the site or tool	Widen scope in /admin/tokens or re-approve OAuth
Project server never loads	.mcp.json server not approved	Approve via /mcp, or claude mcp reset-project-choices

What’s next

• Tokens & scoping — OAuth vs bearer, per-site scopes, risk tiers
• WordPress · Blog posts — first useful prompt
• SOP · Auto-input — how content gets into a template via MCP