mKit — MCP Server Boilerplate for Cloudflare Workers

This repository is a boilerplate for bootstrapping MCP servers on Cloudflare Workers with OAuth 2.1, Stripe billing, and OpenAI Apps SDK UI integration.

Last updated: 2026-01-08 Owner: TBD (set maintainer/team) Review cadence: Quarterly (confirm)

Doc requirements

• Audience tier: Beginner to intermediate

• Scope: Using this repo as a template to configure, run, and deploy an MCP server

• Non-scope: OAuth provider setup details, Stripe account setup, and product-specific UI design

• Required approvals: Maintainer approval for production changes (confirm)

Related MCP server: MCP Server Template for Cloudflare Workers

Table of contents

• Doc requirements

• Risks and assumptions

• Prerequisites

• Quickstart

• Common tasks

• Troubleshooting

• Acceptance criteria

• Evidence bundle

• Reference

Risks and assumptions

• Assumptions: You control a Cloudflare account, OAuth providers, and a Stripe account.

• Risks / blast radius: Misconfigured secrets or webhook signing can cause auth/payment failures.

• Rollback / recovery: Rotate secrets and redeploy; disable affected routes until fixed.

Prerequisites

• Required: Node.js 20+, pnpm, Wrangler CLI, Cloudflare account

• Optional: Stripe and OAuth provider accounts (needed to enable payments and login)

Quickstart

1) Install dependencies

pnpm install

2) Run setup

pnpm setup

This interactive script will:

• Prompt for OAuth credentials (Google/GitHub)

• Prompt for Stripe configuration (optional)

• Generate a secure cookie encryption key

• Create KV namespaces in Cloudflare

• Write .env and update wrangler.jsonc

3) Run locally

pnpm dev
pnpm dev:worker

Run each command in a separate terminal.

4) Verify

Expected output:

• Vite prints a local dev server URL without errors.

• Wrangler prints a local worker URL and no startup errors.

• A request to /mcp returns a non-5xx response.

Common tasks

Create a new tool to expose MCP functionality

• What you get: A new MCP tool registered at server startup.

• Steps:

# Add a new file under src/tools/free/ or src/tools/paid/

• Verify: The tool is registered in the server startup logs.

Add a new widget page for the Apps SDK UI

• What you get: A new auto-discovered widget route.

• Steps:

# Add an HTML file in src/app/routes/ and a React component in src/app/components/

• Verify: The route is present in the generated manifest at build time.

Build and deploy to Cloudflare

• What you get: A live MCP endpoint at your worker URL.

• Steps:

pnpm build-deploy

• Verify: pnpm wrangler deploy reports success and the worker URL responds.

Run quality checks

• What you get: Type safety and test validation.

• Steps:

pnpm typecheck
pnpm lint
pnpm test

• Verify: Each command exits with status 0.

Troubleshooting

Symptom: wrangler dev fails with missing KV namespace

Cause: wrangler.jsonc has placeholder KV IDs. Fix:

pnpm wrangler kv namespace create OAUTH_KV

Update wrangler.jsonc with the real IDs and retry.

Symptom: OAuth login fails or tokens are rejected

Cause: OAuth issuer or JWKS URL is incorrect. Fix: Re-check OAUTH_ISSUER and OAUTH_JWKS_URI in .env.

Symptom: Stripe webhooks are rejected

Cause: Webhook signing secret does not match Stripe configuration. Fix: Update STRIPE_WEBHOOK_SECRET with the value from Stripe dashboard.

Acceptance criteria

• .env created from .env.example with valid values.

• KV namespace IDs set in wrangler.jsonc.

• Local dev runs without startup errors.

• At least one tool is registered and callable.

• Deployment succeeds in Cloudflare.

• Troubleshooting steps are validated by maintainers.

Evidence bundle

• Lint outputs (Vale/markdownlint/link check): Not run (no configs found).

• Brand check output: Not run (no brand check script found).

• Readability output (if available): Not run (no readability script found).

• Checklist snapshot: Pending maintainer confirmation.

Reference

• Project layout: src/worker, src/auth, src/billing, src/tools, src/app

• Commands: pnpm setup, pnpm dev, pnpm dev:worker, pnpm build, pnpm deploy, pnpm test, pnpm lint

• Related docs: docs/architecture.md, docs/development.md, docs/deployment.md, docs/configuration.md, docs/runbook.md

Agent-first workflow

1. Create/update implementation plan using .agent/PLANS.md contract.

2. Validate plan graph:

python3 /Users/jamiecraik/.codex/scripts/plan-graph-lint.py .agent/PLANS.md

3. Run canonical verification:

/Users/jamiecraik/.codex/scripts/verify-work.sh

4. Follow global scaffold policy:

• /Users/jamiecraik/.codex/instructions/agent-first-scaffold-spec.md