MCP Server Template

This template is a remote Model Context Protocol (MCP) server. It runs on Bun and on Cloudflare Workers. It uses the official MCP TypeScript SDK.

The server uses protocol version 2026-07-28. It also accepts clients that use the 2025 protocol versions.

The template includes these functions:

• Checks of the Host and Origin headers.

• OAuth token checks. The server is an OAuth resource server. Your code does not receive the token.

• An error policy. The server does not send internal error data to clients.

• Tests that run on Bun and on Cloudflare Workers.

The sample server gives weather data from Open-Meteo. Open-Meteo does not require an API key. Replace the samples with your tools. Keep the other parts of the template.

Requirements

• Bun 1.4 or later.

• Node.js 22.18 or later. The Wrangler commands and the smoke tests use Node.js.

Related MCP server: MCP Server + Clerk OAuth

Start the server

1. Install the dependencies:

   bun install

2. Start the server:

   bun run dev

The server URL is http://127.0.0.1:3000/mcp.

To use the Cloudflare local runtime, run bun run dev:worker. The server URL is then http://127.0.0.1:8787/mcp.

Connect a client

Use the server URL and the Streamable HTTP transport.

To test the connection, send a request. For example: "What is the weather in Kraków this week?"

Samples

Each sample shows one procedure.

Project structure

src/
  server.ts       Server identity, dependencies, token verification, extra routes, McpServer factory
  settings.ts     Settings for your code, for example API keys
  tools/          ┐
  resources/      │ Your code. Each tool, resource, or prompt has one file.
  prompts/        │ The index.ts file in each folder lists them.
  services/       ┘ Clients for the external APIs that your tools use
  platform/       Template code: configuration, HTTP pipeline, authentication, logs, defineTool
  bun.ts          Entry point for Bun
  worker.ts       Entry point for Cloudflare Workers
tests/            Tests for each tool and service, and tests for the platform code
scripts/          Smoke tests on real network sockets, and a local token issuer

You change server.ts, settings.ts, and the four folders. The platform/ folder is template code. Do not change it unless it is necessary.

platform/ uses only a fixed set of names from server.ts and settings.ts. This lets you replace platform/ with the version from a newer template. server.ts has hooks for settings, runtime resources (for example Workers KV), token verification, authorization server metadata, and extra HTTP routes.

Add a tool

1. Create a file in src/tools/. For example:

   // src/tools/add.ts
   import * as z from 'zod/v4';
   import { defineTool } from '../platform/primitives';
   
   export const add = defineTool(
     'add',
     {
       description: 'Add two numbers.',
       inputSchema: z.object({ a: z.number(), b: z.number() }),
       outputSchema: z.object({ sum: z.number() }),
       annotations: { readOnlyHint: true, openWorldHint: false },
     },
     ({ a, b }) => ({
       content: [{ type: 'text', text: String(a + b) }],
       structuredContent: { sum: a + b },
     }),
   );

2. Add the tool to the list in src/tools/index.ts.

3. Create the test file tests/tools/add.test.ts. Use tests/tools/echo.test.ts as an example.

defineTool has the same arguments as server.registerTool in the SDK. It also does these tasks:

• It gives your dependencies (deps) to the handler as the last argument.

• It makes sure that structuredContent agrees with outputSchema when you compile the code.

• It records unexpected errors in the log. The model does not see these errors.

For errors, progress, cancellation, user input, scopes, and tests, refer to docs/tools.md.

Runtimes

The two runtimes use the same application. Only the entry point is different. For more data, refer to docs/deploy.md.

Configuration

The server identity (name, version, and instructions) is in src/server.ts. The deployment settings are environment variables:

Put your own settings, for example API keys, in src/settings.ts. The server validates them together with the other settings. The file .env.example describes all variables.

If the configuration is not valid, the server shows all problems at the same time:

• Bun does not start.

• A Worker records the problems in the log. It sends a 500 response to all requests until you correct the configuration.

Authentication

The server has three authentication modes:

• none: The server accepts all requests.

• bearer: All clients send the same secret token (BEARER_TOKEN) in the Authorization header.

• oauth: The server is an OAuth resource server. The server publishes metadata that tells clients where your authorization server is. The server accepts only the tokens that your authorization server issued for this server URL.

The server can also be its own authorization server, for example in front of the OAuth of an external provider. For this procedure, refer to docs/auth.md.

To test OAuth without an authorization server, run bun run token. This command starts a local key server. It shows a token and the settings to use. For real providers and scopes for each tool, refer to docs/auth.md.

Scripts

Documentation

• docs/architecture.md: The path of a request through the server, and the function of each layer.

• docs/tools.md: How to write and test tools, resources, and prompts.

• docs/auth.md: OAuth, scopes, and other token checks.

• docs/deploy.md: Cloudflare Workers and Bun in production.

• docs/troubleshooting.md: Frequent errors and their causes.

• CHANGELOG.md: The template versions, and the SDK version that each version uses.

License

MIT