mcp-trellis

Host-agnostische MCP- und OAuth-Ports – du bringst die Laufzeitumgebung und den IdP mit; die Bibliothek besitzt das Connector-Protokoll.

Web-Standard Request → Response. Derselbe Handler auf Cloudflare Workers, Next.js App Router, Deno, Bun und Node HTTP über mcp-trellis/node. Keine Laufzeitabhängigkeiten.

Warum mcp-trellis

Der ganze Connector-Stack in einem Paket – MCP-Handler und OAuth-2.1-Autorisierungsserver – ohne Datenbank und ohne Anbieter-Registrierung. Du kümmerst dich um Login, Token-Erstellung und Speicherung; die Bibliothek besitzt das Protokoll.

Bevorzuge das offizielle SDK, wenn du bereits einen separaten Autorisierungsserver (AS) hast. Bevorzuge workers-oauth-provider, wenn du die Workers-only-Implementierung von Cloudflare nutzen möchtest. Bevorzuge eine verwaltete IdP, wenn du lieber bezahlst, als eine selbst zu betreiben.

Benannte Alternativen im selben Problembereich:

• @mcpauth/auth / getmcpauth / mcp-auth – OAuth für MCP, typischerweise mit einer Datenbank oder einer anderen Laufzeit-/Stack-Annahme. mcp-trellis ist die ohne Abhängigkeiten Option, die den MCP-Handler und den OAuth-2.1-Autorserver in einem Paket mitbringt.

• FastMCP-OAuth – OAuth-Helfer rund um FastMCP. mcp-de-trellis ist host-agnostisch (Request/Response) und nicht an ein bestimmtes MCP-Framework gebunden.

Related MCP server: Remote MCP Server on Cloudflare

Anforderungen

• Node ≥ 20 für Node-Hosts (globale WebCrypto in ESM)

• Oder eine Laufzeit mit WebCrypto + fetch (Workers, Deno, Bun)

Installation

npm install mcp-trellis

Schnellstart

Ein einziger Aufruf richtet den MCP-Endpunkt, den OAuth-Autorisierungsserver und beide Discovery-Dokumente ein:

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) };

Du gibst die audience des Tokens zurück; die Bibliothek lehnt Tokens ab, die für eine andere Ressource ausgestellt wurden, bevor irgendein Tool läuft. Details: docs/security.md.

Ein echter /authorize-Durchlauf umfasst einen Zustimmungsschritt: Eine aufgelöste Sitzung leitet nicht direkt mit einem Code zurück, sondern rendert zuerst einen Consent-Bildschirm (eingebaut oder eigene via consent). wer zum ersten Mal manuell durchklickt, erwartet dort eine HTML-Seite, keine sofortige Weiterleitung – siehe Zustimmung.

Smoke-Test mit curl (Kein Bearer erforderlich):

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

Vorregistrierte Clients, DCR-Umsetzung und clientStore-Anbindung: docs/guide.md#clients.

Architektur

createApp verbindet MCP und OAuth und leitet zwischen ihnen:

Host-Rezepte, Ports, Tools und Multi-Tenant: docs/guide.md.

Dokumentation

Beispiele: examples/ – HTTP-Server, Worker, Multi-Tenant, Stores, Audit.

Mitwirken

PRs sind willkommen – siehe CONTRIBUTING.md.

npm test
npm run build
npm run typecheck

Lizenz

MIT