@maxhealth.tech/mcp-http

OAuth, CORS and observability layer for MCP HTTP servers, built on the official @modelcontextprotocol/server SDK.

Built on the Web Fetch API — runs on Cloudflare Workers, Pages Functions, Deno Deploy, Bun, Node 18+, and any Hono deployment.

Features

• Stateless MCP transport — one WebStandardStreamableHTTPServerTransport per POST, no session state required
• RFC 9728 protected-resource metadata served automatically, at the path-aware route (/.well-known/oauth-protected-resource/mcp for an endpoint mounted at /mcp)
• RFC 8414 /.well-known/oauth-authorization-server (optional)
• Bearer extraction + 401 gate with WWW-Authenticate resource-metadata pointer
• JWT exp early-rejection (configurable, 30 s clock-skew buffer)
• CORS — permissive defaults (*), fully configurable per-origin, or disabled
• forwardBearer(token) — inject the caller's token into upstream fetch calls
• Observability — onRequest hook with outcome, status, and duration
• Error handling — onError hook with JSON-RPC 500 fallback
• Adapters — first-class Hono and Cloudflare Pages Functions adapters

Install

# bun
bun add @maxhealth.tech/mcp-http @modelcontextprotocol/server

# npm
npm install @maxhealth.tech/mcp-http @modelcontextprotocol/server

# pnpm
pnpm add @maxhealth.tech/mcp-http @modelcontextprotocol/server

@modelcontextprotocol/server is a peer dependency (^2.0.0). hono is an optional peer dependency (≥ 4.12.0) — only needed for the /hono adapter.

Upgrading from 0.2.x? The peer moved from the retired monolithic @modelcontextprotocol/sdk to @modelcontextprotocol/server. Every export still works — see Migrating from 0.2.x.

Quick start

Cloudflare Workers

import { createWorkerFetch, forwardBearer } from "@maxhealth.tech/mcp-http";
import { McpServer } from "@modelcontextprotocol/server";

export default {
  fetch: createWorkerFetch({
    authorizationServer: "https://auth.example.com",
    createServer: (token) => {
      const server = new McpServer({ name: "my-api", version: "1.0.0" });
      // Register tools, resources, prompts…
      // Use forwardBearer(token) to call upstream APIs with the caller's token
      return server;
    },
  }),
};

Hono

import { Hono } from "hono";
import { mcpHono } from "@maxhealth.tech/mcp-http/hono";
import { forwardBearer } from "@maxhealth.tech/mcp-http";

const app = new Hono<{ Bindings: Env }>();

app.route(
  "/",
  mcpHono({
    authorizationServer: "https://auth.example.com",
    createServer: (token, { c }) => {
      const server = new McpServer({ name: "my-api", version: "1.0.0" });
      const fetchFn = forwardBearer(token);
      const fhirUrl = c.env.FHIR_BASE_URL;
      // Register tools using fetchFn and fhirUrl…
      return server;
    },
  }),
);

export default app;

Cloudflare Pages Functions

// functions/[[path]].ts
import { mcpPagesFunction } from "@maxhealth.tech/mcp-http/cloudflare";
import { forwardBearer } from "@maxhealth.tech/mcp-http";

export const onRequest = mcpPagesFunction({
  authorizationServer: "https://auth.example.com",
  createServer: (token, { env }) => {
    const server = new McpServer({ name: "my-api", version: "1.0.0" });
    // Use forwardBearer(token) for upstream calls
    return server;
  },
});

Generic (any runtime)

import { createMcpHttpHandler } from "@maxhealth.tech/mcp-http";

const handler = createMcpHttpHandler({
  authorizationServer: "https://auth.example.com",
  createServer: (token) => buildMyMcpServer(token),
});

// Use with any runtime that supports Request → Response
Bun.serve({ fetch: handler });
Deno.serve(handler);

Configuration

createMcpHttpHandler(config) accepts a McpHttpHandlerConfig object: