Skip to main content
Glama
jezweb

MCP Server Template for Cloudflare Workers

by jezweb
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

MCP Server Template for Cloudflare Workers

A production-ready template for building MCP (Model Context Protocol) servers on Cloudflare Workers with better-auth social login.

Features

  • better-auth Social Login - Google, Microsoft, and GitHub OAuth with automatic session management

  • MCP OAuth Provider - Dynamic client registration for Claude.ai and Claude Code

  • Cloudflare Workers - Serverless deployment with global edge distribution

  • D1 Database - SQLite-compatible database with Drizzle ORM

  • Durable Objects - Persistent MCP session storage

  • MCP Tools - Example tools with error handling patterns

  • MCP Resources - Read-only data exposure (future-ready for Claude.ai)

  • MCP Prompts - Templated prompt definitions (future-ready for Claude.ai)

  • Marketing homepage - Professional landing page in Jezweb style

  • Admin Dashboard - Manage tokens, view tools/resources/prompts

  • AI Chat Testing - Built-in AI chat to test MCP tools (Workers AI + external providers)

  • Multi-Provider AI - Workers AI (free), OpenAI, Anthropic, Google AI Studio

  • Conversation Memory - D1-backed persistent chat history with configurable TTL

  • Internal Agent - Optional ask_agent tool with Workers AI gatekeeper for voice agents

Quick Start

1. Clone and Install

# Copy this template to your new project cp -r mcp-server-template-cloudflare my-new-mcp cd my-new-mcp # Install dependencies npm install

2. Configure Cloudflare

Update wrangler.jsonc:

{ "name": "my-new-mcp", // Your worker name "kv_namespaces": [ { "binding": "OAUTH_KV", "id": "YOUR_KV_NAMESPACE_ID" // Create with: npx wrangler kv:namespace create OAUTH_KV } ], "d1_databases": [ { "binding": "DB", "database_name": "my-mcp-db", "database_id": "YOUR_D1_DATABASE_ID" // Create with: npx wrangler d1 create my-mcp-db } ], "durable_objects": { "bindings": [ { "name": "MCP_OBJECT", "class_name": "MyMCP" // Update if you rename the class } ] }, "migrations": [ { "tag": "v1", "new_sqlite_classes": ["MyMCP"] // Must match class_name above } ], "vars": { "ENABLE_CONVERSATION_MEMORY": "true", // D1-backed chat history "ENABLE_INTERNAL_AGENT": "false" // ask_agent tool (for voice agents) } }

3. Set Up OAuth Provider (Google)

  1. Go to Google Cloud Console

  2. Create a new project or select existing

  3. Enable the APIs you need (e.g., Google Tasks API, Calendar API)

  4. Go to "APIs & Services" → "Credentials"

  5. Create OAuth 2.0 Client ID (Web application)

  6. Add authorized redirect URI: https://your-worker.workers.dev/api/auth/callback/google

Note: better-auth uses /api/auth/callback/{provider} pattern for OAuth callbacks.

Alternative Providers (Microsoft Entra, GitHub):

  • See docs/BETTER_AUTH_ARCHITECTURE.md for setup instructions

  • Each provider requires its own OAuth app and secrets

4. Set Secrets

# Required: Google OAuth echo "YOUR_GOOGLE_CLIENT_ID" | npx wrangler secret put GOOGLE_CLIENT_ID echo "YOUR_GOOGLE_CLIENT_SECRET" | npx wrangler secret put GOOGLE_CLIENT_SECRET # Required: better-auth session encryption python3 -c "import secrets; print(secrets.token_hex(32))" | npx wrangler secret put BETTER_AUTH_SECRET # Required: Cookie encryption for approved clients python3 -c "import secrets; print(secrets.token_hex(32))" | npx wrangler secret put COOKIE_ENCRYPTION_KEY # Optional: For Bearer token authentication python3 -c "import secrets; print(secrets.token_urlsafe(32))" | npx wrangler secret put AUTH_TOKEN # Optional: Microsoft Entra # echo "YOUR_MS_CLIENT_ID" | npx wrangler secret put MICROSOFT_CLIENT_ID # echo "YOUR_MS_CLIENT_SECRET" | npx wrangler secret put MICROSOFT_CLIENT_SECRET # Optional: GitHub # echo "YOUR_GH_CLIENT_ID" | npx wrangler secret put GITHUB_CLIENT_ID # echo "YOUR_GH_CLIENT_SECRET" | npx wrangler secret put GITHUB_CLIENT_SECRET

5. Deploy

npx wrangler deploy

Customization

Update Server Identity

  1. src/index.ts: Update class name, server name, and tools

  2. src/oauth/google-handler.ts: Update GOOGLE_SCOPES and homepage content

  3. wrangler.jsonc: Update worker name and class references

Google OAuth Scopes

Edit GOOGLE_SCOPES in src/oauth/google-handler.ts:

// Basic user info const GOOGLE_SCOPES = 'openid email profile'; // Google Tasks const GOOGLE_SCOPES = 'openid email profile https://www.googleapis.com/auth/tasks'; // Google Calendar (read-only) const GOOGLE_SCOPES = 'openid email profile https://www.googleapis.com/auth/calendar.readonly'; // Gmail (read-only) const GOOGLE_SCOPES = 'openid email profile https://www.googleapis.com/auth/gmail.readonly';

Adding Tools

Add tools in the init() method of your MCP class:

this.server.tool( 'tool_name', // Unique identifier 'Tool description.', // Shown to Claude { param1: z.string().describe('Parameter description'), param2: z.number().optional().describe('Optional parameter'), }, async ({ param1, param2 }) => { try { // For Google API calls, use authorizedFetch(): const response = await this.authorizedFetch( `https://api.example.com/endpoint?param=${param1}` ); if (!response.ok) { const error = await response.text(); throw new Error(`API error: ${error}`); } const data = await response.json(); return { content: [{ type: 'text', text: `Result: ${JSON.stringify(data)}` }], }; } catch (error) { const message = error instanceof Error ? error.message : 'Unknown error'; return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true, }; } } );

Adding Resources

Resources expose read-only data that LLMs can access. Add resources in the init() method:

this.server.resource( 'resource_name', // Unique identifier 'mcp://my-mcp/resource-path', // URI for the resource { description: 'What this resource provides', mimeType: 'application/json', }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ // Your data here }, null, 2), }], }) );

Note: Claude.ai doesn't support resources yet (as of Dec 2025), but the API does. Adding resources now future-proofs your server.

Adding Prompts

Prompts are templated prompt definitions (like slash commands). Add prompts in the init() method:

this.server.prompt( 'prompt_name', // Unique identifier 'Description of what this prompt does', { content: z.string().describe('Required parameter'), option: z.string().optional().describe('Optional parameter'), }, async ({ content, option }) => ({ messages: [{ role: 'user', content: { type: 'text', text: option ? `Process this with ${option}: ${content}` : `Process this: ${content}`, }, }], }) );

Note: Claude.ai doesn't support prompts yet (as of Dec 2025), but the API does. Adding prompts now future-proofs your server.

Admin Dashboard

Access the admin dashboard at /admin after logging in with Google OAuth.

Features:

  • View server info, tools, resources, and prompts

  • Create and manage Bearer auth tokens

  • AI Chat for testing MCP tools

Admin Setup:

Set admin emails (comma-separated):

echo "admin@example.com,user@example.com" | npx wrangler secret put ADMIN_EMAILS

AI Chat Testing

The admin dashboard includes an AI-powered tool tester:

  1. Click the chat bubble icon in the bottom-right corner

  2. Select an AI provider (Workers AI is free)

  3. Ask the AI to test tools, e.g., "test the hello tool with name John"

Supported Providers:

  • Workers AI (Free) - Llama 3.3 70B and other models, no API key needed

  • OpenAI - GPT-4o, GPT-4o-mini, o1

  • Anthropic - Claude 3.5 Sonnet, Claude 3.5 Haiku

  • Google AI Studio - Gemini 2.5 Pro, Gemini 2.5 Flash

  • Groq - Fast inference with Llama 3.3 70B

All external providers use AI Gateway's Compat endpoint - a single OpenAI-compatible API that works for all providers. The gateway handles format conversion automatically.

Setting up External Providers (BYOK - Recommended):

The easiest way is to configure API keys in AI Gateway (no code changes needed):

  1. Go to Cloudflare Dashboard → AI → AI Gateway

  2. Create a gateway named default (or use existing)

  3. Enable Authenticated Gateway (required for BYOK)

  4. Go to Provider Keys → Add API Key

  5. Select provider (OpenAI, Anthropic, etc.) and enter your API key

  6. Create a Gateway Token: User API Tokens → Create → select AI Gateway permissions

  7. Set the token as a Worker secret: echo "token" | npx wrangler secret put CF_AIG_TOKEN

  8. Redeploy: npx wrangler deploy

Keys are securely stored and automatically injected into requests.

Alternative: Environment Secrets

You can also set API keys as Worker secrets (overrides BYOK):

# Anthropic echo "sk-ant-..." | npx wrangler secret put ANTHROPIC_API_KEY # OpenAI echo "sk-..." | npx wrangler secret put OPENAI_API_KEY # If using Authenticated Gateway, also set: echo "your-gateway-token" | npx wrangler secret put CF_AIG_TOKEN # Don't forget to redeploy after setting secrets! npx wrangler deploy

Note: Workers AI is free and works out of the box. External providers go through Cloudflare AI Gateway for logging, caching, and centralized key management.

AI Gateway Features

The template uses AI Gateway's Compat endpoint - a single OpenAI-compatible API for all providers. Additional features available:

Per-Request Headers (add to your AI calls):

Header

Purpose

Example

cf-aig-cache-ttl

Cache responses (seconds)

3600 = 1 hour

cf-aig-skip-cache

Bypass cache

true

cf-aig-request-timeout

Trigger fallback if slow (ms)

10000

cf-aig-metadata

Tag for analytics

{"userId":"..."}

Response Headers (check after AI calls):

Header

Meaning

cf-aig-cache-status

HIT or MISS

cf-aig-step

Which fallback was used (0 = primary)

Dashboard-Only Features (configure in Cloudflare dashboard):

  • Guardrails - Content filtering, prompt injection detection

  • DLP - Detect PII, secrets, source code in prompts/responses

  • Rate Limiting - Gateway-level request limits

  • Dynamic Routing - A/B testing, geographic routing, user-based routing

  • Analytics - Usage metrics, costs, error rates

See AI Gateway docs for details.

Architecture

src/ ├── index.ts # Main MCP class with tools, resources, prompts + helper methods ├── types.ts # TypeScript interfaces (Env, Props, ToolMetadata, ChatMessage) │ ├── lib/ │ ├── auth.ts # better-auth configuration (social providers, OAuth Provider plugin) │ ├── db/ │ │ ├── index.ts # Drizzle D1 database setup │ │ └── schema.ts # better-auth tables + custom tables (Drizzle ORM) │ ├── ai/ │ │ ├── index.ts # AI Gateway client │ │ ├── providers.ts # Provider/model registry │ │ └── openrouter.ts # Dynamic model fetching from OpenRouter │ ├── memory/ │ │ └── index.ts # D1-backed conversation memory │ ├── agent/ │ │ └── index.ts # Internal agent pattern (Workers AI gatekeeper) │ ├── crypto.ts # Timing-safe token comparison │ └── rate-limit.ts # KV-based rate limiting │ ├── admin/ │ ├── routes.ts # Admin API endpoints │ ├── ui.ts # Admin dashboard HTML/CSS/JS │ ├── chat.ts # AI chat handler with tool execution + D1 memory │ ├── middleware.ts # Admin auth middleware │ ├── session.ts # Admin session management │ └── tokens.ts # Bearer token CRUD │ ├── oauth/ # MCP OAuth protocol handlers │ ├── better-auth-handler.ts # OAuth routes via better-auth sessions │ └── workers-oauth-utils.ts # CSRF, state, approval dialog utilities │ ├── pages/ │ ├── homepage.ts # Server homepage (marketing landing page) │ └── login.ts # Social login page (Google, Microsoft, GitHub) │ ├── tools/ │ ├── index.ts # Tool registry (single source of truth) │ ├── types.ts # Tool type definitions │ ├── utility.ts # Utility tools (no auth) │ ├── user.ts # User tools (require OAuth) │ └── examples.ts # Example API call patterns │ ├── resources/ │ ├── index.ts # Resource registry │ ├── types.ts # Resource type definitions │ └── server.ts # Server info resources │ ├── prompts/ │ ├── index.ts # Prompt registry │ ├── types.ts # Prompt type definitions │ └── templates.ts # Prompt templates │ └── migrations/ ├── 0001_better_auth_tables.sql # better-auth core tables (user, session, account, etc.) ├── 0002_custom_tables.sql # Custom tables (conversation memory, tool execution) └── 0003_add_jwks_table.sql # JWT key rotation table (better-auth v1.4.0)

Key Components

  • MyMCP: Extends McpAgent with your tools, resources, and prompts

  • ensureValidToken(): Automatically refreshes expired tokens

  • authorizedFetch(): Wrapper for API calls with auth

  • BetterAuthHandler: Hono app handling OAuth routes via better-auth

  • createAuth(): better-auth instance factory with D1 + Drizzle

Included Examples

Utility Tools (no auth required):

Name

Description

hello

Simple greeting

get_current_time

Current date/time in various timezones

generate_uuid

Generate UUID v4 (1-10)

base64

Encode/decode Base64 strings

text_stats

Count words, characters, lines

random_number

Generate random numbers in range

json_format

Format/validate JSON

hash_text

Generate SHA-256 hash

User Tools (require OAuth):

Name

Description

get_user_info

Returns authenticated user's Google info

list_my_conversations

List your conversation history

Example Tools:

Name

Description

example_api_call

Demonstrates authorizedFetch() pattern

Resources (read-only data):

Name

Description

server_info

Server metadata and capabilities

user_profile

Authenticated user's profile

Prompts (templates):

Name

Description

summarize

Content summarization template

analyze

Content analysis template (sentiment/technical/business)

Conversation Memory

The template includes optional D1-backed conversation memory for persistent chat history.

Setup:

# 1. Create D1 database npx wrangler d1 create my-mcp-db # 2. Add database_id to wrangler.jsonc d1_databases section # 3. Run migrations npx wrangler d1 execute my-mcp-db --local --file=migrations/0001_conversations.sql npx wrangler d1 execute my-mcp-db --remote --file=migrations/0001_conversations.sql # 4. Enable in wrangler.jsonc vars "ENABLE_CONVERSATION_MEMORY": "true"

Configuration:

Variable

Default

Description

ENABLE_CONVERSATION_MEMORY

false

Enable D1 conversation storage

CONVERSATION_TTL_HOURS

168

Auto-delete conversations after 7 days

MAX_CONTEXT_MESSAGES

50

Max messages to load for context

When disabled, falls back to KV storage (backwards compatible).

Internal Agent

The template includes an optional internal agent pattern for voice agents (e.g., ElevenLabs) and prompt injection protection.

When enabled, the server exposes an ask_agent tool that wraps all other tools behind a Workers AI gatekeeper.

Enable:

// In wrangler.jsonc vars "ENABLE_INTERNAL_AGENT": "true", "INTERNAL_AGENT_MODEL": "@cf/qwen/qwen2.5-coder-32b-instruct"

How it works:

  1. External caller uses only ask_agent tool with natural language query

  2. Workers AI gatekeeper validates the request

  3. Internal agent selects and calls appropriate tools

  4. Clean response returned (no raw tool exposure)

Benefits:

  • Security layer against prompt injection from audio

  • Minimal context passed to inner agent (fast)

  • All tools available through single interface

Configuration:

Variable

Default

Description

ENABLE_INTERNAL_AGENT

false

Enable ask_agent tool

INTERNAL_AGENT_MODEL

@cf/qwen/qwen2.5-coder-32b-instruct

Workers AI gatekeeper model

Token Refresh

The template includes automatic token refresh:

  1. authorizedFetch() calls ensureValidToken() before each request

  2. If token expires within 5 minutes, it's refreshed proactively

  3. New tokens are persisted to Durable Object storage

  4. 401 responses invalidate the stored token

This prevents sessions from disconnecting after 1 hour (Google token expiry).

Testing

Local Development

npx wrangler dev

Test with curl

# Test MCP endpoint (requires AUTH_TOKEN secret set) curl -X POST "https://your-worker.workers.dev/mcp" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

Dependencies

  • @cloudflare/workers-oauth-provider - OAuth 2.0 provider for Workers

  • @modelcontextprotocol/sdk - MCP protocol implementation

  • agents - McpAgent base class with Durable Object integration

  • hono - Lightweight web framework for OAuth routes

  • zod - Schema validation for tool parameters

Security

The template includes multiple security layers:

XSS Protection:

  • HTML escaping for all dynamic content in admin dashboard

  • Data attributes with event delegation (no inline onclick handlers)

  • Content Security Policy headers on admin routes

Session Security:

  • SameSite=Strict cookies prevent CSRF attacks

  • Timing-safe token comparison prevents timing attacks

  • Secure, HttpOnly cookies for admin sessions

Input Validation:

  • All tool inputs have max length limits (1MB default)

  • Chat message size limit (100KB)

  • Safe JSON parsing with fallbacks

Rate Limiting:

  • Admin chat: 30 requests/minute per user

  • Token creation: 10/hour per user

Access Control:

  • User-owned conversations (OAuth email verification)

  • Admin-only dashboard routes

  • Bearer token authentication for programmatic access

Future MCP Features

See docs/MCP_FEATURES_PLAN.md for planning around:

  • Tool Search - defer_loading for 85% token reduction (10+ tools)

  • Sampling - Server requests LLM completion from client (agentic workflows)

  • Completions - Autocomplete for prompt/resource arguments

License

MIT License - See LICENSE for details.

Built by Jezweb — AI agents, MCP servers, and business automation.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jezweb/google-calendar-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server