MCP Worker Template

A Cloudflare Worker template for building MCP (Model Context Protocol) servers with OAuth 2.1 + PIN authentication.

Works with Claude.ai web and Claude Code CLI out of the box.

Features

• OAuth 2.1 + PIN: Secure access via PIN-protected authorization
• D1 Storage: OAuth tokens stored in Cloudflare D1
• MCP Protocol: JSON-RPC based tool calling
• Example Tool: Includes echo tool as a starting point

Quick Start

1. Create Your Project

# Clone or copy this template
cd my-mcp-server
npm install

# Create D1 database
wrangler d1 create my-mcp-server

# Update wrangler.toml with your database_id

2. Initialize Database

wrangler d1 execute my-mcp-server --file=schema.sql

3. Set Authorization PIN

wrangler secret put AUTHORIZE_PIN
# Enter a secure PIN when prompted

4. Deploy

wrangler deploy

5. Connect Claude.ai Web

1. Go to Claude.ai Settings > Connectors
2. Click "Add custom connector"
3. Enter your worker URL: https://my-mcp-server.YOUR-SUBDOMAIN.workers.dev
4. Enter your PIN when prompted

6. Connect Claude Code CLI

claude mcp add --transport http \
  my-mcp-server https://my-mcp-server.YOUR-SUBDOMAIN.workers.dev/mcp

Adding Custom Tools

Edit src/mcp.ts:

1. Add your tool definition to TOOLS:

const TOOLS = {
  echo: { ... },
  my_tool: {
    name: 'my_tool',
    description: 'What this tool does',
    inputSchema: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: 'Parameter description' },
      },
      required: ['param1'],
    },
  },
};

2. Add the handler in the tools/call switch:

case 'my_tool': {
  const param1 = args['param1'] as string;
  result = await doSomething(param1, env);
  break;
}

Customization

Server Name and Scopes

Edit src/oauth.ts:

const SERVER_NAME = 'My MCP Server';
const SCOPES = ['my:read', 'my:write'];

Adding D1 Tables

Add tables to schema.sql and types to src/types.ts.

Architecture

Cloudflare Worker
    ├── OAuth 2.1 (DCR, PKCE, PIN auth)
    └── D1 (token storage)

License

MIT