mcp-trellis

Host-agnostic MCP + OAuth ports — you bring the runtime and IdP; the library owns the connector protocol.

Web-standard Request → Response. Same handler on Cloudflare Workers, Next.js App Router, Deno, Bun, and Node HTTP via mcp-trellis/node. Zero runtime dependencies.

Why mcp-trellis

The whole connector stack in one package — MCP handler and OAuth 2.1 authorization server — with no database and no vendor signup. You own login, token minting, and storage; the library owns the protocol.

	mcp-trellis	Official MCP SDK	workers-oauth-provider	@mcpauth/auth	Auth0 / Clerk / Authlete
MCP handler	✅	✅	❌	❌	❌
OAuth 2.1 authorization server	✅	❌ bring your own	✅	✅	✅
Runtime	any Web-standard	any Web-standard	Workers only	Node	—
Database	none	—	KV (optional)	required	—
Runtime dependencies	zero	several	several	several	—
Self-hosted	✅	✅	✅	✅	❌ SaaS
Named connector profiles (Claude / Gemini / Codex), enforced	✅	❌	❌	❌	❌

Prefer the official SDK when you already have a separate AS. Prefer workers-oauth-provider when you want Cloudflare's Workers-only implementation. Prefer a managed IdP when you'd rather pay than operate one.

Named alternatives in the same problem space:

• @mcpauth/auth / getmcpauth / mcp-auth — OAuth for MCP, typically with a DB or a different runtime/stack assumption. mcp-trellis is the zero-dependency option that ships the MCP handler and the OAuth 2.1 AS in one package.
• fastmcp-oauth — OAuth helpers around FastMCP. mcp-trellis is host-agnostic (Request/Response) and not tied to a particular MCP framework.

Requirements

• Node ≥ 20 for Node hosts (global WebCrypto in ESM)
• Or any runtime with WebCrypto + fetch (Workers, Deno, Bun)

Install

npm install mcp-trellis

Quick start

One call mounts the MCP endpoint, the OAuth authorization server, and both discovery documents:

import { createMcpApp } from "mcp-trellis";

const app = createMcpApp({
  serverInfo: { name: "demo", version: "1.0.0" },
  clients: ["claude"],
  tools: [
    {
      name: "echo",
      description: "Echo text back",
      inputSchema: {
        type: "object",
        properties: { text: { type: "string" } },
        required: ["text"],
      },
      scope: "mcp",
      handler: (_ctx, args) => String(args.text ?? ""),
    },
  ],
  auth: {
    codeSecret: process.env.OAUTH_CODE_SECRET!,
    resolveUser: async (req) => getSession(req),
    loginUrl: (_req, next) => `/login?next=${encodeURIComponent(next)}`,
    mintAccessToken: async ({ userId, scope, resource }) => ({
      // Embed `resource` as the token audience (RFC 8707).
      accessToken: await issueUserToken(userId, { aud: resource, scope }),
      expiresIn: 3600,
    }),
    verifyToken: async (token) => {
      const claims = await readUserToken(token);
      if (!claims) return null;
      return {
        userId: claims.sub,
        scopes: claims.scope.split(" "),
        audience: claims.aud,
      };
    },
  },
});

export default { fetch: (req: Request) => app.fetch(req) };

You return the token's audience; the library rejects tokens minted for a different resource before any tool runs. Details: docs/security.md.

A real /authorize walk includes an approval step: a resolved session doesn't redirect straight back with a code, it renders a consent screen first (built in, or your own via consent). First-time integrators clicking through by hand should expect an HTML page there, not an immediate redirect — see Consent.

Smoke-test with initialize (public — no Bearer needed):

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"demo","version":"1.0.0"},"instructions":""}}

Clients

Client	Registration	Token endpoint auth	Notes
claude	Dynamic (DCR), public + PKCE	none	Claude Custom Connectors callback allowlisted
gemini	Pre-registered, confidential	client_secret_basic, client_secret_post	Supply auth.clientStore
codex	OAuth 2.1 per MCP auth spec, public + PKCE	none	ChatGPT / Codex share one contract

Pre-registered clients, DCR enforcement, and clientStore wiring: docs/guide.md#clients.

Architecture

createMcpApp wires MCP and OAuth and routes between them:

Host recipes, ports, tools, and multi-tenant: docs/guide.md.

Docs

Doc	Contents
docs/guide.md	Architecture, clients, recipes, ports, tools, multi-tenant
docs/reference.md	Routes, methods, status codes, options, exports
docs/security.md	Protocol promises, threat model, not in scope
docs/ROADMAP.md	What's next

Examples: examples/ — HTTP server, Worker, multi-tenant, stores, audit.

Contributing

PRs welcome — see CONTRIBUTING.md.

npm test
npm run build
npm run typecheck

License

MIT