OAuth 2.1 MCP Server

Una plantilla de Next.js para construir servidores MCP con autenticación OAuth 2.1, compatible con PostgreSQL y Redis.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Servidor MCP OAuth 2.1 como una aplicación Next.js en Vercel

Nota: fue bifurcado de: https://github.com/run-llama/mcp-nextjs con los siguientes cambios:

  • prisma reemplazado con drizzle ORM
  • next-auth reemplazado con better-auth

Esta es una aplicación basada en Next.js que proporciona un servidor MCP (Model Context Protocol) con soporte de autenticación OAuth 2.1. Está pensada como un modelo para construir tu propio servidor MCP en un contexto Next.js. Utiliza el @vercel/mcp-adapter para manejar el protocolo MCP, con el fin de soportar tanto los transportes SSE como Streamable HTTP.

Además de ser un servidor OAuth, también requiere que el usuario se autentique. Actualmente está configurado para usar Google como proveedor, pero podrías autenticar usuarios como quieras (X, GitHub, tu propia base de datos de usuarios/contraseñas, etc.) sin romper el flujo OAuth.

Uso con

Claude Desktop y Claude.ai

Claude actualmente solo soporta el transporte SSE más antiguo, por lo que necesitas darle una URL diferente a todos los demás clientes listados aquí.

Usa el botón "Connect Apps" y selecciona "Add Integration". Proporciona la URL como https://example.com/mcp/sse (¡el /sse al final es importante!). Ten en cuenta que Claude Desktop y Web no aceptarán una URL localhost.

Cursor

Edita tu mcp.json para que se vea así:

{
  "mcpServers": {
      "MyServer": {
        "name": "MCP OAuth Demo",
        "url": "https://example.com/mcp/mcp",
        "transport": "http-stream"
      },
  }
}

VSCode

VSCode actualmente no expulsa correctamente el ID de cliente, por lo que el registro del cliente falla si accidentalmente eliminas el cliente (la solución alternativa en ese issue lo resolverá). Por lo demás, funciona bien. Añade esto a tu settings.json:

"mcp": {
    "servers": {
        "My Server": {
            "url": "https://example.com/mcp/mcp"
        }
    }
}

Si eliminaste el cliente, necesitas abrir la Paleta de Comandos y ejecutar Authentication: Remove Dynamic Authentication Providers para expulsar el ID de cliente de VSCode.

MCP Inspector

Dile a Inspector que se conecte a https://example.com/mcp/mcp, con transporte Streamable HTTP.

Nota, abre el enlace con MCP_PROXY_AUTH_TOKEN:

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...
   (Auto-open is disabled when authentication is enabled)

También puedes usar el transporte SSE conectándote a https://example.com/mcp/sse en su lugar.

Ejecutando el servidor

pnpm install
pnpm run db:generate
pnpm run dev

La primera vez también necesitarás ejecutar pnpm run db:push para crear las tablas de la base de datos.

Variables de entorno

Las variables de entorno requeridas deben estar en .env:

DATABASE_URL="postgresql://user:pass@server/database"
BETTER_AUTH_SECRET="any random string"
GOOGLE_CLIENT_ID="a Google OAuth client ID"
GOOGLE_CLIENT_SECRET="a Google OAuth client secret"
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
NEXT_PUBLIC_BASE_URL=http://localhost:3000
REDIS_URL="redis://user:pass@host:6379"

DATABASE_URL es requerido para que la autenticación OAuth funcione, aquí es donde viven las sesiones, etc.

REDIS_URL es requerido si necesitas que el transporte SSE funcione (es decir, quieres soportar Claude Desktop y Web).

Comandos de base de datos

Comandos comunes de Drizzle ORM:

  • pnpm run db:generate - Generar cliente de base de datos desde el esquema
  • pnpm run db:push - Enviar cambios de esquema a la base de datos (desarrollo)
  • pnpm run db:migrate - Generar y ejecutar migraciones (producción)
  • pnpm run db:studio - Abrir Drizzle Studio para ver/editar datos

Arquitectura

Si estás usando esto como plantilla para tu propia aplicación Next.js, las partes importantes son:

  • /src/app/api/oauth/* - estos implementan el registro de clientes oauth y el intercambio de tokens
  • /src/app/oauth/authorize/page.tsx - esto implementa la pantalla de consentimiento oauth (es extremadamente básica por ahora)
  • /src/mcp/[transport]/route.ts - esto implementa el propio servidor MCP. Tus herramientas, recursos, etc. deben definirse aquí.

Para manejar OAuth, tu aplicación necesita poder persistir clientes, tokens de acceso, etc. Para hacer esto, está usando una base de datos PostgreSQL accedida a través de Drizzle ORM. Puedes cambiarla por otra base de datos si quieres (será más fácil si es otra base de datos compatible con Drizzle).

Esquema de base de datos

El esquema de la base de datos se define en src/lib/db/schema.ts usando Drizzle ORM. Las tablas principales son:

  • accounts - información de cuenta de NextAuth.js
  • sessions - sesiones de usuario
  • users - cuentas de usuario
  • verificationTokens - tokens de verificación de correo electrónico
  • oauthClients - clientes OAuth registrados
  • oauthAccessTokens - tokens de acceso emitidos
  • oauthAuthCodes - códigos de autorización para el flujo OAuth

También notarás:

  • src/app/auth.ts - esto implementa la autenticación Auth.js para tu propia aplicación. Está configurado para usar Google como proveedor, pero puedes cambiarlo para usar cualquier otro proveedor soportado por Auth.js. Esto no es requerido para que el servidor MCP funcione, pero es una buena idea tenerlo en su lugar para tu propia aplicación.
  • src/app/api/auth/[...nextauth]/route.ts - esto conecta la autenticación Auth.js, y nuevamente no es parte de la implementación OAuth.

Despliegue a producción

Esta aplicación solo funciona si se despliega en Vercel actualmente, debido a su dependencia del paquete @vercel/mcp-adapter, que a su vez es requerido para soportar el antiguo transporte SSE. No nos pareció bien implementar un protocolo extra completo solo para Claude Desktop.

Despliega como de costumbre. Necesitarás añadir pnpm run db:generate a tu comando de build, y por supuesto necesitarás todas las mismas variables de entorno que en el entorno de desarrollo.