Cloudflare Scaffold

A remote MCP server deployed to Cloudflare Workers, protected by Cloudflare Access for SaaS (OIDC), connectable from Claude.ai as a custom connector.

Includes a mock vector database as a demo — swap it for Vectorize, D1, or any real backend.

Architecture

Claude.ai ──OAuth──▶ Worker (/authorize, /token, /register, /mcp)
                       │
                       └──OIDC──▶ Cloudflare Access (SaaS app)
                                    │
                                    └──▶ Identity Provider (One-time PIN, Google, etc.)

The Worker runs @cloudflare/workers-oauth-provider as the OAuth 2.1 server that Claude.ai talks to. It delegates user authentication to Cloudflare Access (configured as an OIDC SaaS app), which in turn federates to whichever IdP you wire up.

Project layout

├── src/
│   ├── index.ts            # MCP server + OAuth provider entry point
│   └── access-handler.ts   # Access OIDC code-exchange handler
├── wrangler.jsonc
└── package.json

MCP tools included

Tool	Description
vector_search	Natural language search against the vector store
vector_get	Retrieve a document by ID
vector_list	List all stored document IDs
vector_upsert	Insert or update a document
vector_delete	Delete a document by ID
health	Health check with user info and doc count

Setup

Prerequisites

• Node.js 20+ and npm
• Wrangler CLI (npm install -g wrangler or use npx wrangler)
• A Cloudflare account
• A Zero Trust team name chosen at https://one.dash.cloudflare.com (first-time prompt). This becomes <team>.cloudflareaccess.com.
• At least one identity provider wired into Zero Trust under Settings → Authentication → Login methods. For a POC, "One-time PIN" needs no configuration.

1. Authenticate Wrangler

npx wrangler login

Opens a browser for OAuth. For CI/headless, create a Cloudflare API Token (My Profile → API Tokens → "Edit Cloudflare Workers" template) and export CLOUDFLARE_API_TOKEN.

2. Clone and install

git clone https://github.com/w00jay/MCP-server-cloudflare-scaffold.git
cd MCP-server-cloudflare-scaffold
npm install

3. Create the KV namespace

npx wrangler kv namespace create OAUTH_KV

Copy the returned id and replace YOUR_KV_NAMESPACE_ID in wrangler.jsonc.

4. Create the Access for SaaS OIDC app

In https://one.dash.cloudflare.com:

1. Access controls → Applications → Add an application → SaaS
2. Application: type your app name and click the textbox (custom app, not gallery)
3. Authentication protocol: OIDC
4. Click Add application
5. Scopes: check openid, email, profile
6. Redirect URLs: https://<worker-name>.<your-subdomain>.workers.dev/callback
   • Deploy once first (npx wrangler deploy) to discover your subdomain, or check your Workers dashboard.
7. Copy these five values (some only shown once):
   • Client ID
   • Client secret
   • Authorization endpoint
   • Token endpoint
   • Key endpoint (JWKS)
8. Click Next

Create the Access policy

1. Add a policy
2. Policy name: e.g. allow-mcp
3. Action: Allow
4. Session duration: 24 hours
5. Configure rules → Include:
   • Selector: Emails → your email
   • Or: Emails ending in → @yourcompany.com
6. Click Next

Pick identity providers

1. Check the IdPs you want (One-time PIN is simplest for POC)
2. If only one IdP, enable Instant Auth to skip the picker screen
3. Next → Add application

5. Set Worker secrets

Use the values from the Cloudflare One SaaS app page, NOT from an upstream IdP (Google, GitHub, etc.). Access is the OAuth provider to your Worker; it federates to your IdP underneath.

npx wrangler secret put ACCESS_CLIENT_ID
npx wrangler secret put ACCESS_CLIENT_SECRET
npx wrangler secret put ACCESS_AUTHORIZATION_URL
npx wrangler secret put ACCESS_TOKEN_URL
npx wrangler secret put ACCESS_JWKS_URL
npx wrangler secret put COOKIE_ENCRYPTION_KEY     # openssl rand -hex 32

6. Deploy

npm run deploy
# or: npx wrangler deploy

Worker is now live at https://vector-mcp.<your-subdomain>.workers.dev.

7. Smoke-test with Workers AI Playground

1. Open https://playground.ai.cloudflare.com
2. Under MCP Servers, enter https://<worker-name>.<your-subdomain>.workers.dev/mcp
3. Click Connect → Approve
4. Complete the Access login (OTP email or your IdP)
5. You should see "Connected" and the vector_* tools listed

8. Add to Claude.ai

1. Settings → Connectors → Add custom connector
2. URL: https://<worker-name>.<your-subdomain>.workers.dev/mcp
3. Leave Advanced Settings empty — the Worker advertises Dynamic Client Registration, so Claude registers itself. Do NOT paste the Access client credentials here; those stay on the Worker.
4. Click Add → Connect
5. Complete the Access login flow in the popup
6. The vector_* tools should appear in your tool list

Troubleshooting

Symptom	Cause / Fix
defaultHandler must be either an ExportedHandler...	access-handler.ts missing its export. Verify with grep -n "export" src/access-handler.ts.
302 redirect loop on /authorize	Wrong ACCESS_AUTHORIZATION_URL secret, or redirect URL on the SaaS app doesn't match https://<worker>.workers.dev/callback.
Token exchange failed in /callback	ACCESS_CLIENT_SECRET mismatch or ACCESS_TOKEN_URL typo.
Access login succeeds but Claude shows error	Email not in policy include rule. Edit the Access policy.
Claude can't reach the Worker at all	You may have a self-hosted Access app on the same hostname. Use SaaS type, not Self-hosted.

Live logs: npm run tail or npx wrangler tail

Caveats

• id_token signature is not verified. The handler decodes the JWT payload but doesn't validate against ACCESS_JWKS_URL. Fine behind Access for a POC; for production add jose and verify.
• Vector store is in-memory in the Durable Object instance and resets on eviction. Swap for D1, Vectorize, or KV for persistence.
• SSE transport is included at /sse for legacy MCP clients but is deprecated; new clients should use /mcp.

License

MIT