xmcp Boilerplate

xmcp-boilerplate

Vercel's xmcp boilerplate — a Model Context Protocol server built with xmcp, where each tool, prompt and resource is a file (src/tools/greet.ts, src/prompts/review-code.ts, src/resources/(config)/app.ts, src/resources/(users)/[userId]/index.ts) and xmcp serves them over Streamable HTTP at /mcp — running natively as a Cloudflare Worker, and packaged as an Orun baseline: one command takes a new MCP server from nothing to live on stage and prod, in its own repository, under its own name — in ONE landing.

xmcp build --cf compiles the template's files into xmcp's own Cloudflare Worker (worker.js): Streamable HTTP at /mcp, stateless — no session, so any isolate answers any call — xmcp's landing page at / and a health check. wrangler deploys it through a three-line entry (src/worker.ts) whose one addition is that GET /health also names the server and the environment the Worker runs, which the deploy smoke-tests before it makes an MCP call. The template's files are the template's files, unchanged. The port moves the template from xmcp 0.5 (which had no Cloudflare build) to xmcp 1.9 and from zod 3.24 to zod 4 (xmcp 1.x needs zod 3.25 or later, and on zod 3.25's types the template's prompt fails to compile), and adds the Worker's config, the monorepo wrapper, a test package and the deploy contract. What the baseline adds is everything needed to make a copy of it somebody else's — built the way cirrus-baseline is. See specs/epics/xmcp-boilerplate for the design, the milestones and the as-built status.

Instantiating a product

git clone --depth 1 --branch <baseline-tag> https://github.com/sourceplane/xmcp-boilerplate
cd xmcp-boilerplate
orun new --blueprint repo-blueprint.yaml --out ~/mcp/acme-mcp --run-hooks --resume \
  --set reponame=acme-mcp --set productname="Acme MCP" \
  --set githuborg=acme-inc --set subdomain=<workers-dev-subdomain>

Or, once the platform's registry lists it, from the Orun console (Baselines → xmcp-boilerplate → Build). Two phases — 01-product (the repository, its CI and the whole server in one pull request, deployed to stage and prod by one convergence, smoke-tested) and 02-docs (the live deployment recorded) — each landing one pull request in the new repository. BOOTSTRAP.md is the operator guide; docs/phases/ has a page per phase.

The new repository receives the server only — the Worker, its tests, its CI, its tooling, a README of its own, its operating contract and the template's licence — renamed throughout to the server's name, repository and Cloudflare Worker. None of this repository's machinery ships, and nothing that ships names it.

What is here (the product)

Getting started

pnpm install
pnpm typecheck
pnpm lint
pnpm test             # builds the server first (xmcp build --cf), then the suite
pnpm build            # xmcp build --cf, then wrangler deploy --dry-run → apps/api/dist

Run it locally. xmcp dev is the template's own development server (Node, reloading on save); preview builds the Worker and serves it under workerd:

pnpm --filter @app/api dev          # the template's: xmcp dev
pnpm --filter @app/api preview      # xmcp build --cf, then wrangler dev → http://localhost:8787
curl http://localhost:8787/health   # {"status":"ok",…,"name":"xmcp server","environment":"local"}
curl -X POST http://localhost:8787/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Add a tool by adding a file to apps/api/src/tools/ (a schema, a metadata and a default export, as greet.ts has); prompts and resources the same way in their folders. Any MCP client connects to http://localhost:8787/mcp (the MCP Inspector: npx @modelcontextprotocol/inspector). /mcp is open, as the template has it: add xmcp's auth (its middleware or an API key) before a tool does anything a stranger should not.

How it maps to Vercel

CI

Credits

The server is Vercel's xmcp boilerplate (vercel/examples, framework-boilerplates/xmcp, MIT — apps/api/LICENSE.md), built with xmcp.