@phake/mcp

A TypeScript library for building MCP (Model Context Protocol) servers - works on both Cloudflare Workers and Node.js.

Why @phake/mcp?

• Multiple auth strategies: OAuth 2.1, Google/GitHub presets, Bearer, API Key, Custom headers
• Encrypted token storage: AES-256-GCM at rest + proactive refresh
• Cloudflare Workers native: KV storage, memory fallback, zero config
• Production-ready: CIMD validation, OAuth discovery, DNS rebinding protection
• Quick scaffold: bun create @phake/mcp to get started

See Comparison Guide for full feature comparison with official SDK.

Requirements

• Bun 1.x or Node.js 20+
• Wrangler CLI (for Cloudflare Workers deployments)
• A Cloudflare account with Workers and KV access (for Worker deployments)

Installation

bun add @phake/mcp
# or
npm install @phake/mcp

Quick Start (Scaffold)

Scaffold a new MCP server with one command:

# Interactive (prompts for template)
bun create @phake/mcp

# With options
bun create @phake/mcp my-mcp-app --template cloudflare-workers --install

Available templates:

| Template | Description | |----------|-------------| | cloudflare-workers | Cloudflare Workers + Hono (default) | | cloudflare-workers-google | Cloudflare Workers + Google OAuth | | node-hono | Node.js + Bun + Hono |

Options:

| Option | Description | |--------|-------------| | -t, --template | Template name | | -i, --install | Auto install dependencies | | -p, --pm | Package manager: npm, bun, yarn, pnpm |

Getting Started

1. Create the KV namespace

wrangler kv namespace create TOKENS

2. Bind it in your Wrangler config

wrangler.toml

[[kv_namespaces]]
binding = "TOKENS"
id = "<your-kv-namespace-id>"

3. Generate an encryption key

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

4. Set the encryption key

Production:

wrangler secret put RS_TOKENS_ENC_KEY

Local development - add to .dev.vars:

RS_TOKENS_ENC_KEY=<your-generated-key>

5. Create your Worker

import { createMCPServer } from "@phake/mcp";

const server = createMCPServer({
  adapter: "worker",
  tools: [/* your tools */],
});

export default server;

For detailed setup, see Getting Started Guide.

Usage

Defining Tools

import { z } from "zod";
import { defineTool } from "@phake/mcp";

const greetTool = defineTool({
  name: "greet",
  description: "Returns a greeting for the given name",
  inputSchema: z.object({
    name: z.string().describe("Name to greet"),
  }),
  outputSchema: z.object({
    message: z.string().describe("The greeting message"),
  }),
  handler: async (args) => {
    return { message: `Hello, ${args.name}!` };
  },
});

Authenticated Tools

const profileTool = defineTool({
  name: "get_profile",
  description: "Fetch the authenticated user's profile",
  inputSchema: z.object({}),
  requiresAuth: true,
  handler: async (_args, context) => {
    const response = await fetch("https://api.example.com/me", {
      headers: context.resolvedHeaders,
    });
    return await response.json();
  },
});

Cloudflare Bindings

Access Cloudflare worker bindings (AI, Vectorize, D1, R2, KV, etc.) in your tools:

import { createMCPServer, defineTool, type ToolContext } from "@phake/mcp";

interface Env extends Cloudflare.Env {
  AI: unknown;
  VECTORIZE: unknown;
  MY_BUCKET: unknown;
}

const searchTool = defineTool({
  name: "search_vectors",
  inputSchema: z.object({ query: z.string() }),
  handler: async (args, context: ToolContext<Env>) => {
    // Type-safe access to bindings
    const ai = context.bindings?.AI;
    const vectorize = context.bindings?.VECTORIZE;
    
    return {
      content: [{
        type: "text",
        text: `AI: ${!!ai}, Vectorize: ${!!vectorize}`
      }]
    };
  },
});

const server = createMCPServer<Env>({
  tools: [searchTool],
});

Getting User Info (OAuth)

Fetch user profile from OAuth providers using context.getUser():

const userTool = defineTool({
  name: "get_user_info",
  requiresAuth: true,
  inputSchema: z.object({}),
  handler: async (_, context) => {
    // Get token with error handling
    const { data: token, error: tokenError } = context.getToken();
    if (tokenError || !token) {
      return { content: [{ type: "text", text: tokenError }], isError: true };
    }

    // Get user info with error handling
    const { data, error } = await context.getUser();
    if (error || !data) {
      return { content: [{ type: "text", text: error }], isError: true };
    }

    return {
      content: [{
        type: "text",
        text: JSON.stringify({ email: data.email, name: data.name })
      }]
    };
  },
});

The getUser() method automatically detects the provider based on AUTH_STRATEGY:

• google → https://www.googleapis.com/oauth2/v2/userinfo
• github → https://api.github.com/user

Authentication Strategies

| Strategy | Description | |----------|-------------| | oauth | Full OAuth 2.1 PKCE flow with RS token => provider token mapping | | google | Same as OAuth with Google preset endpoints | | github | Same as OAuth with GitHub preset endpoints | | bearer | Static Bearer token | | api_key | Static API key via header | | custom | Arbitrary custom headers | | none | No authentication |

See Authentication Guide for detailed configuration.

API Reference

createMCPServer(options)

Creates an MCP server instance.

const server = createMCPServer({
  adapter: "worker",
  tools: [greetTool, profileTool],
});

defineTool(def)

Type-safe tool factory. See API Reference for the full field reference.

toolFail(defaults)

Creates a typed error factory with preset default fields:

const fail = toolFail({ ok: false, items: null });
return fail("spreadsheet_id is required");
// => { ok: false, items: null, error: "spreadsheet_id is required" }

Built-in Tools

| Tool | Input | Output | Description | |------|-------|--------|-------------| | echo | { message, uppercase? } | { echoed, length } | Echoes back a message | | health | { verbose? } | { status, timestamp, runtime, uptime? } | Reports server health |

Package Exports

| Export | Path | Description | |--------|------|-------------| | Core | @phake/mcp | defineTool, createMCPServer, helpers | | Worker runtime | @phake/mcp/runtime/worker | Cloudflare Workers adapter | | Node runtime | @phake/mcp/runtime/node | Node.js adapter (experimental) |

Contributing

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Build
bun run build

License

MIT