# 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

```bash
# 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`:

```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](https://console.cloud.google.com/)
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

```bash
# 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

```bash
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`:

```typescript
// 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:

```typescript
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:

```typescript
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:

```typescript
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):

```bash
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](https://dash.cloudflare.com/) → **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):

```bash
# 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](https://dash.cloudflare.com/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](https://developers.cloudflare.com/ai-gateway/) 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` class**: 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:**

```bash
# 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:**

```jsonc
// 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

```bash
npx wrangler dev
```

### Test with curl

```bash
# 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](LICENSE) for details.

---

Built by [Jezweb](https://jezweb.com.au) — AI agents, MCP servers, and business automation.