- Developers who want their product in Claude, ChatGPT and other MCP clients as a remote connector with proper sign-in.
- Teams whose agent scaffolded an MCP server and who want it checked against the spec and the connector directory requirements.
- Agencies who build connectors for clients and want the same tested starting point each time.
Remote MCP Server Kit
Builds a production remote MCP server on Cloudflare Workers with OAuth sign-in, tool design rules, rate limits and tests, then checks it against the MCP spec and the connector directory requirements with a bundled script.
- Node 18 or newer for the verify script. The template tooling (Wrangler 4, Vitest 4) needs a current Node LTS.
- A Cloudflare account with Workers, KV, service bindings and the Rate Limiting binding. The template deploys two Workers: an authorization server and the MCP server.
- A GitHub OAuth app for the example sign-in. The template shows how to swap in another provider, your own accounts or an emailed code.
Every file, and a preview of the main ones.
The tree lists everything in the zip. The previews show the first part of each main file, so you can judge the real code before you buy.
Preview the files
Everything in the zip (28 files)
- remote-mcp-server/
- LICENSE
- README.md
- SKILL.md preview
- references/
- directory-checklist.md
- tool-design.md
- scripts/
- verify-mcp.mjs preview
- template/
- .gitignore
- package.json
- README.md
- tsconfig.json
- vitest.config.ts
- wrangler.auth.jsonc
- wrangler.jsonc
- src/
- auth.ts
- authorize.ts
- consent.ts
- env.ts
- index.ts preview
- tools.ts
- test/
- auth.test.ts
- entry.test.ts
- helpers.ts
- mcp.test.ts
- templates/
- server.json
- test/
- verify.test.mjs
- fixtures/
- tools-bad.json
- tools-good.json
- wrangler-comments.jsonc
remote-mcp-server/SKILL.mdLines 1 to 76 of 137---
name: remote-mcp-server
description: Build, secure, test, deploy and list a production remote MCP server on Cloudflare Workers. Designs the tools, scaffolds a stateless Streamable HTTP server from the bundled template with OAuth 2.1 sign-in (a separate authorization server Worker with a consent page), adds scope checks, rate limits and safe errors, runs the tests, and proves the result with the bundled verify-mcp.mjs script. Then prepares the MCP Registry server.json and the connector directory checklist. Use when asked to build a remote MCP server or connector, add OAuth to an MCP server, put an API behind MCP on Workers, fix an MCP server for a connector directory, or check an existing MCP endpoint.
license: Commercial. See LICENSE.
metadata:
version: "1.0.0"
author: Red Center Studio
---
# Remote MCP server on Cloudflare Workers
You are building a remote MCP server that people connect to from Claude, ChatGPT, Cursor and other MCP clients, with OAuth sign-in, on Cloudflare Workers. Work in the eight phases below, in order. Phase 7 is the gate: the job is done when the script passes, not when the code exists.
Paths in this file are relative to this skill's folder. `template/` is a complete, tested project to copy. `scripts/verify-mcp.mjs` needs Node 18 or newer and has no dependencies.
## Ground rules
1. **Copy the template, then change it.** It is pinned to versions that compile and pass together (`agents` 0.33.0, `@modelcontextprotocol/server` 2.4.0, `@cloudflare/workers-oauth-provider` 1.2.4, `zod` 4.6.7). Do not upgrade any of them while building; upgrade later, on purpose, with the tests running.
2. **Read the installed types when the docs and the code disagree.** These packages move fast. If an example does not compile, open the package's `.d.ts` in `node_modules` and follow it.
3. **The entry modules export only `default`.** Workers treats every named export of a Worker's entry file as an entrypoint, and a named export that is not a handler stops the Worker from starting. Unit tests do not catch this. `template/test/entry.test.ts` and the `--dir` check do.
4. **Never invent facts** in tool descriptions, server instructions, the consent page or listing text: no claims about directory approval, security certifications, uptime or customers that the user has not given you.
5. **Secrets live in wrangler secrets only.** Never in `vars`, source, tests, chat or logs. Never ask the user to paste a secret into the chat; give them the `wrangler secret put` command to run.
6. **Ask before anything that costs money, publishes, or touches a live account:** deploying, creating Cloudflare resources, publishing to the registry, submitting to a directory. Prepare everything, then ask.
7. **Tokens are bound to one URL.** `MCP_SERVER_URL` is exactly what clients connect to, identical in both Workers. Decide the final URL (ideally a custom domain) before the first deploy.
## Phase 1: Design the tools
1. Ask the user what people should be able to do through the server, and what data it touches. Write the answers down as a short list of user requests ("find last month's unpaid invoices", "mark an invoice paid").
2. Turn the requests into tools, following `references/tool-design.md`. Aim for the fewest tools that cover the requests. Keep reads and writes in separate tools, and split out anything that sends, pays or deletes.
3. For each tool, write a table row: name, one-line description, inputs with limits, what it returns, and the five annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
4. Decide the scopes. Default: `mcp:read` for every read tool, `mcp:write` for every write tool. Add a scope only for a group of tools a user might reasonably refuse on its own.
5. Decide how people sign in (Phase 3). The template uses GitHub. If the users are not developers, plan the swap now.
6. Show the user the tool table and the scopes and get a yes before writing code.
## Phase 2: Scaffold from the template
1. Copy `template/` to the project folder (or a subfolder of an existing repository). Do not copy `node_modules` or `.wrangler`.
2. Rename, everywhere it appears:
- `name` in `wrangler.jsonc` and `wrangler.auth.jsonc`, and `services[0].service` in `wrangler.jsonc` (must equal the authorization server's name)
- `SERVER_INFO` in `src/tools.ts`
- `SERVICE_NAME` and `USER_AGENT` in `src/authorize.ts`
- `name` in `package.json`
3. Set `compatibility_date` in both wrangler files to today.
4. Set the URLs. `MCP_SERVER_URL` (both files, identical, ending in the route, default `/mcp`), `AUTH_SERVER_URL` (MCP server) equal to `ISSUER` (authorization server). Replace every `YOUR-SUBDOMAIN`; the `--dir` check fails while any placeholder is left.
5. Replace the example tools in `src/tools.ts` with the tools from Phase 1. Keep: `guard()` around every handler, `ok()` and `toolError()` for results, `scopeChallenge: requireScopes(WRITE_SCOPE)` and the `needsWrite()` check on every write tool, a strict zod schema with limits, and annotations on every tool. Replace the `NOTES` KV binding with the storage the tools need (D1, KV, R2, or an upstream API).
6. Update `INSTRUCTIONS` in `src/index.ts` and the scope wording in `src/consent.ts` (`SCOPE_TEXT`).
7. Run `npm install` and `npm run check`. Fix type errors before going on.
## Phase 3: OAuth
The template's split is the current Cloudflare pattern:
| Worker | Library class | Job |
|---|---|---|
| Authorization server (`src/auth.ts` entry, `src/authorize.ts` logic) | `OAuthAuthorizationServer` | Metadata, client registration, consent page, sign-in, tokens, `validateToken` over RPC |
| MCP server (`src/index.ts`) | `OAuthResourceServer` | Protected resource metadata, 401 challenge, token check over the `AUTH_SERVER` service binding, then `createMcpHandler` |
1. Keep consent before sign-in. `describeConsent`, `beginConsent`, `approveConsent` and `denyConsent` bind the form to the browser with a `__Host-` cookie and block framing; the form carries only the handle. Every client-supplied string on the page is escaped (`escapeHtml` in `src/consent.ts`). Do not remove either.
2. Keep both registration methods on: `clientIdMetadataDocumentEnabled: true` (needs the `global_fetch_strictly_public` flag on the authorization server) and `clientRegistrationEndpoint: "/oauth/register"` for clients that still use Dynamic Client Registration.
3. Sign-in. With GitHub as shipped: the user creates a GitHub OAuth app with callback `ISSUER/callback` and sets `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` with `npx wrangler secret put NAME -c wrangler.auth.jsonc`. `ALLOWED_GITHUB_LOGINS` restricts who may sign in. To use another method, change only `startSignIn()` and `callback()` in `src/authorize.ts`; `template/README.md` explains the options (another OAuth provider, your own sessions, an emailed code).
4. `props` passed to `completeAuthorization()` reach every tool call. Keep `userId` stable per person, do not store tokens unless a tool needs them, and never return or log them.
5. Scopes: `requiredScopes` on the resource server is advertised, not enforced. The template enforces `mcp:read` in `handleMcp` with `insufficientScope()`, and write tools return a `403 insufficient_scope` challenge for `mcp:write` through `scopeChallenge`, so clients can ask the user for more access (step-up).
6. The validator calls the RPC method on the binding: `(env) => (resource, token) => env.AUTH_SERVER.validateToken(resource, token)`. Passing the method itself (`env.AUTH_SERVER.validateToken`), as some examples show, answered 503 to every request through a local service binding.
## Phase 4: Limits and errors
1. Rate limits (Workers Rate Limiting bindings): `TOOL_LIMITER` per signed-in user on every tool call (in `guard()`), `AUTH_LIMITER` per IP on the sign-in pages. Size the limits for real use; the shipped numbers are a starting point. Hosted clients share a few IP addresses, so never rate limit the MCP endpoint per IP alone.
2. Request size: `MAX_REQUEST_BYTES` in `src/tools.ts` caps the body (413). Every string and number in every schema has a limit.
3. Result size: page lists with a cursor, cap page size in the schema, keep large fields out of list results.
4. Errors: tool problems return `isError: true` with a message that says what to do next. `guard()` catches anything thrown, logs it with `console.error` (visible in Workers Logs) and returns a plain message. No stack traces, no internal messages, no SQL in results.
5. Data isolation: every query is scoped to `props.userId` in the query itself, never filtered afterwards.
6. Custom domain: the handler's `allowedHostnames` comes from `MCP_SERVER_URL`. Browser origins are checked by `createMcpHandler`; if a browser-based client on another origin must connect, add it with `corsOptions.origin` or `allowedOriginHostnames`, never with `"*"` unless something else checks origins first.
## Phase 5: Tests
The template's tests run in the Workers runtime (`@cloudflare/vitest-plugin`) and cover the whole path with a fake GitHub: metadata, consent page escaping, forged form, deny, full sign-in, read-only grants, the 401 challenge, protected resource metadata, every tool, per-user isolation, the `insufficient_scope` step-up, schema errors, pagination, the size limit, GET returning 405, errors without stack traces, CORS, and entry module exports.
Preview ends at line 76. The file continues for 61 more lines in the kit.
remote-mcp-server/scripts/verify-mcp.mjsLines 1 to 80 of 763#!/usr/bin/env node
// verify-mcp.mjs: checks a remote MCP server, live or as a Cloudflare Workers project on disk.
// No dependencies. Needs Node 18 or newer.
//
// node verify-mcp.mjs --url https://mcp.example.com/mcp
// node verify-mcp.mjs --url https://mcp.example.com/mcp --token <access token>
// node verify-mcp.mjs --dir ./my-mcp-server
//
// Options:
// --url <url> Check a live MCP endpoint: initialize, tools/list, the 401 challenge, protected resource metadata,
// authorization server metadata, GET on the endpoint, CORS preflight.
// --token <t> With --url: a bearer access token, so the checks behind sign-in run too. Or set MCP_TOKEN.
// The token is never printed.
// --dir <path> Check a Workers project: wrangler config, compatibility date and flags, secrets in vars,
// tool annotations, error handling, .gitignore.
// --strict Treat warnings as failures.
// --json Print the results as JSON instead of text.
//
// Exit code 0 when nothing failed, 1 when at least one check failed, 2 when the arguments are wrong.
import { execFileSync } from "node:child_process";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { dirname, join, relative, resolve } from "node:path";
import { pathToFileURL } from "node:url";
/** Protocol revisions this script knows. A server may answer with any of them. */
export const KNOWN_PROTOCOLS = ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"];
const ASK_PROTOCOL = "2025-11-25";
const TIMEOUT_MS = 15000;
const pass = (area, message) => ({ level: "pass", area, message });
const warn = (area, message, fix, where) => ({ level: "warn", area, message, fix, where });
const fail = (area, message, fix, where) => ({ level: "fail", area, message, fix, where });
// ---------- shared helpers ----------
const lineOf = (text, index) => (index < 0 ? undefined : text.slice(0, index).split("\n").length);
/** Remove // and /* comments and trailing commas from JSONC, leaving strings (and URLs in them) alone. */
export function stripJsonc(text) {
let out = "";
let inStr = false;
for (let i = 0; i < text.length; i++) {
const c = text[i];
const n = text[i + 1];
if (inStr) {
out += c;
if (c === "\\") out += text[++i] ?? "";
else if (c === '"') inStr = false;
} else if (c === '"') {
inStr = true;
out += c;
} else if (c === "/" && n === "/") {
while (i < text.length && text[i] !== "\n") i++;
out += "\n";
} else if (c === "/" && n === "*") {
i += 2;
while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
if (text[i] === "\n") out += "\n";
i++;
}
i++;
} else out += c;
}
// Trailing commas, again outside strings.
let res = "";
inStr = false;
for (let i = 0; i < out.length; i++) {
const c = out[i];
if (inStr) {
res += c;
if (c === "\\") res += out[++i] ?? "";
else if (c === '"') inStr = false;
continue;
}
if (c === '"') inStr = true;
if (c === ",") {
let j = i + 1;
while (j < out.length && /\s/.test(out[j])) j++;
if (out[j] === "}" || out[j] === "]") continue;
}
Preview ends at line 80. The file continues for 683 more lines in the kit.
remote-mcp-server/template/src/index.tsLines 1 to 37 of 83// MCP server (OAuth resource server) on Cloudflare Workers.
//
// Request path:
// client -> OAuthResourceServer (401 + resource metadata without a valid token; token checked over the AUTH_SERVER
// service binding) -> scope and size checks below -> createMcpHandler (stateless Streamable HTTP) -> tools.ts
//
// Stateless: a new McpServer is built for every request, so nothing is kept between requests except what the tools
// store themselves (KV here). GET and DELETE on /mcp answer 405, as the stateless transport has no session stream.
//
// This is the Worker's entry module: it exports only `default`. Workers treats every named export of the entry
// module as an entrypoint, and a named export that is not a handler (a constant, say) stops the Worker from starting.
// Shared values live in tools.ts.
import { OAuthResourceServer, insufficientScope, type OAuthResourceContext } from "@cloudflare/workers-oauth-provider";
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import type { AuthProps, McpEnv } from "./env";
import { MAX_REQUEST_BYTES, READ_SCOPE, SERVER_INFO, registerTools } from "./tools";
/** Sent to the model once per connection. Say what the server is for and the order to use the tools in. */
const INSTRUCTIONS =
"Personal notes for the signed-in user. Use list_notes to find a note, get_note to read it, create_note and update_note to write, " +
"and delete_note only after the user confirms. Write tools need the connection to have write access.";
const rpcError = (status: number, code: number, message: string) =>
Response.json({ jsonrpc: "2.0", id: null, error: { code, message } }, { status, headers: { "cache-control": "no-store" } });
/** Runs for every request that carries a valid token for MCP_SERVER_URL. */
async function handleMcp(request: Request, env: McpEnv, ctx: OAuthResourceContext<AuthProps>): Promise<Response> {
// requiredScopes below is advertised to clients, not enforced. Enforce it here.
if (!ctx.auth.scope.includes(READ_SCOPE)) return insufficientScope(ctx.auth, [READ_SCOPE]);
if (request.method === "POST") {
if (Number(request.headers.get("content-length") ?? 0) > MAX_REQUEST_BYTES) return rpcError(413, -32600, "Request too large.");
const body = await request.arrayBuffer();
if (body.byteLength > MAX_REQUEST_BYTES) return rpcError(413, -32600, "Request too large.");
request = new Request(request, { body });
}
Preview ends at line 37. The file continues for 46 more lines in the kit.
Eight phases, in order.
The agent follows SKILL.md from the first phase to the last. It is not done until verify-mcp.mjs passes.
- Design the tools. Turns what people should be able to do into the fewest tools, with reads and writes kept apart, limits on every input and the five tool annotations.
- Scaffold from the template. Copies the two-Worker template, renames it, sets the URLs and runs the template tests before changing anything.
- OAuth. Keeps the split OAuth pattern: an authorization server with a consent page and sign-in, and an MCP server that checks every token and its scopes.
- Limits and errors. Rate limits per user and per IP, caps on request and result size, and errors that say what to do next without leaking internals.
- Tests. Updates the Workers-runtime tests for the new tools: a good call, a bad input, another user who must not see the data, and a read-only token on every write tool.
- Deploy. Deploys with your yes: you set the secrets, the authorization server goes first, then the MCP server.
- Verify and finish. Runs verify-mcp.mjs on the project and the live endpoint, with a token for the checks behind sign-in, until it passes.
- Listing. Prepares the MCP Registry server.json and goes through the connector directory checklist with you. Nothing is published without your say.
Unzip it where your agent looks for skills.
Claude Code, this project
mkdir -p .claude/skills && unzip remote-mcp-kit-v1.0.0.zip -d .claude/skills/Cursor
mkdir -p .cursor/skills && unzip remote-mcp-kit-v1.0.0.zip -d .cursor/skills/Antigravity
mkdir -p .agent/skills && unzip remote-mcp-kit-v1.0.0.zip -d .agent/skills/Then ask in plain words, for example: "Use the remote-mcp-server skill on this project."
Remote MCP Server Kit
$39 USD
- Price
- $39 USD, paid once through Stripe. No subscription.
- Licence
- One purchase covers one person or one company. Use the kit on as many projects as you like, your own and your clients'. What you build with it is yours. You may not resell, share or publish the kit itself, or hand a client the kit's folder to reuse.
- Delivery
- Pay once through Stripe Checkout. You land on a download page with your zip, and the same download link is emailed to you. It works for 30 days and up to 10 downloads.
- Version
- Version 1.0.0, updated 20 November 2026.
- Updates
- Each kit has a version number. Updates within version 1 are free: email Hello@redcenterstudio.com with your order id and you get a new download link.
- Refunds
- If a kit has a major problem we cannot fix, you can ask for a refund. Your rights under Australian Consumer Law apply in full. Email Hello@redcenterstudio.com. See the terms for the kits and your rights under Australian Consumer Law.
Remote MCP Server Kit questions
What does the template include?
Two Cloudflare Workers: an authorization server with a consent page, GitHub sign-in and tokens, and an MCP server that checks every token over a service binding and runs the tools. Example tools show strict input schemas, read-only and destructive annotations, scope checks on write tools, rate limits and errors that say what to do next. Tests run in the Workers runtime.
Can I use a sign-in other than GitHub?
Yes. Sign-in lives in two functions. The template's README explains how to switch to another OAuth provider, your own session cookie or an emailed one-time code without changing the consent page, the token endpoint or the MCP server.
What does verify-mcp.mjs check?
Against a live endpoint: initialize, tools/list, the 401 challenge, the protected resource and authorization server metadata, GET on the endpoint and a CORS preflight, plus the checks behind sign-in when you pass a token. On a project folder: the wrangler config, compatibility date and flags, secrets in vars, tool annotations, error handling and .gitignore.
Does passing the script get my connector listed in a directory?
No. Directory listings are reviewed by the people who run them. The kit checks the technical requirements it can test and includes a checklist for the rest, so you submit with fewer surprises.
Other Agent Skill kits.
GEO Skill Kit
Free
Audits a website for AI search readiness, fixes robots.txt rules, structured data, canonical and Open Graph tags and llms.txt, then proves the result with a zero-dependency check script.
Stripe on Workers Kit
$19 USD
Adds Stripe Checkout, a signature-checked webhook and idempotent order fulfilment to a Cloudflare Worker with no Stripe SDK, then tests the webhook path with a bundled script.
Workers Launch Check Kit
$15 USD
Reviews a Cloudflare Workers project before launch: secrets, security headers, rate limits, error handling, observability and wrangler config, fixes what fails and re-runs the bundled checker until it passes.