mcp-trellis

Puertos MCP + OAuth independientes del host — tú aportas el runtime y el IdP; la librería se encarga del protocolo del conector.

Request → Response según el estándar web. El mismo handler en Cloudflare Workers, Next.js App Router, Deno, Bun y Node HTTP mediante mcp-trellis/node. Cero dependencias en tiempo de ejecución.

Por qué mcp-trellis

Toda la pila del conector en un solo paquete — el handler de MCP y el servidor de autorización OAuth 2.1 — sin base de datos ni registro de proveedor. Tú controlas el inicio de sesión, la emisión de tokens y el almacenamiento; la librería controla el protocolo.

Elige el SDK oficial si ya tienes un servidor de autorización aparte. Elige workers-oauth-provider si quieres la implementación exclusiva para Workers de Cloudflare. Elige un IdP gestionado si prefieres pagar en vez de operarlo.

Alternativas destacadas en el mismo espacio de solución:

• @mcpauth/auth / getmcpauth / mcp-auth — OAuth para MCP, normalmente con una base de datos o con suposiciones de runtime/stack distintas. mcp-trellis es la opción cero dependencias que incluye el handler de MCP y el servidor de autorización OAuth 2.1 en un solo paquete.

• fastmcp-oauth — Helpers de OAuth para FastMCP. mcp-trellis es independiente del host (Request/Response) y no está ligado a un framework de MCP concreto.

Related MCP server: Remote MCP Server on Cloudflare

Requisitos

• Node ≥ 20 para hosts de Node (WebCrypto global en ESM)

• O cualquier runtime con WebCrypto + fetch (Workers, Deno, Bun)

Instalación

npm install mcp-trellis

Inicio rápido

Una sola llamada monta el endpoint de MCP, el servidor de autorización OAuth y ambos documentos de descubrimiento:

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

Devuelves el audience del token; la librería rechaza tokens emitidos para un recurso distinto antes de que se ejecute cualquier herramienta. Detalles: docs/security.md.

Un flujo /authorize real incluye un paso de aprobación: una sesión resuelta no redirige inmediatamente de vuelta con un código, sino que primero muestra una pantalla de consentimiento (integrada o propia mediante consent). Quienes lo integran por primera vez y hace clic manualmente deberían esperar una página HTML ahí, no una redirección inmediata — cons Consentimiento.

Prueba rápida con initialize (público — no se necesita dar un Bearer):

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":""}}

Clientes

Clientes pre-registrados, aplicación de DCR y cableado de clientStore: docs/guide.md#clients.

Arquitectura

createMcpApp conecta MCP y OAuth y enruta entre ellos:

Recetas de host, puertos, herramientas y multi-tendencia: docs/guide.md.

Documentación

Contribuciones

Se aceptan PRs; consulta CONTRIBUTING.md.

npm test
npm run build
npm run typecheck

Licencia

MIT