mcp-use + Scalekit MCP Auth

Un servidor MCP de mcp-use que se autentica con Scalekit OAuth 2.1.

Los compañeros de equipo comparten una única URL de servidor. Cada persona inicia sesión. Las herramientas ven su identidad (ctx.auth.user.id), no una clave de API compartida.

Este ejemplo no usa @scalekit-sdk/node y no necesita un id o secreto de cliente de Scalekit. El servidor de recursos verifica los JWT contra los JWKS de Scalekit.

La guía práctica estilo cookbook está en docs/v2/typescript/server/authentication/providers/scalekit.mdx. Este README es el manual de operaciones de este repositorio.

[!IMPORTANT] Usa tu propio entorno de Scalekit. Este repositorio solo incluye marcadores de posición. Nunca hagas commit de .env.

Lo que obtienes

• MCP HTTP streamable en /mcp

• 401 + WWW-Authenticate que apunta a los metadatos de protected-resource de la RFC 9728

• Scalekit como servidor de autorización (DCR y CIMD)

• whoami — usuario autenticado, scopes y iss / aud del token

• greet — una herramienta que se basa en ctx.auth.user.id

Related MCP server: Access Self-Hosted MCP Server

Cómo inicia sesión un cliente

sequenceDiagram
  participant Client as MCP client
  participant Server as This server
  participant SK as Your Scalekit env

  Client->>Server: POST /mcp (no token)
  Server-->>Client: 401 + WWW-Authenticate
  Client->>Server: GET /.well-known/oauth-protected-resource/mcp
  Server-->>Client: authorization_servers = Scalekit resource issuer
  Client->>SK: Discover AS metadata, register via DCR or CIMD
  Client->>SK: User signs in and consents
  SK-->>Client: Access token (aud includes res_…)
  Client->>Server: POST /mcp Authorization: Bearer …
  Server-->>Client: Tool result scoped to ctx.auth.user.id

Requisitos previos

• Node.js 22.22.2 o superior

• Una cuenta de Scalekit (regístrate si no tienes una)

• Al menos un método de autenticación habilitado (Google, GitHub, sin contraseña o SSO empresarial)

1. Registrar un servidor MCP en Scalekit

Sigue la guía de inicio rápido de MCP Auth con estos valores:

1. Abre el panel de Scalekit → MCP servers → Add MCP server.

2. Ponle un nombre. Ese nombre aparece en la pantalla de consentimiento.

3. Habilita dynamic client registration y Client ID Metadata Document (CIMD). Los clientes públicos como Inspector, Claude y Cursor necesitan al menos una de estas opciones; mantén ambas activadas.

4. En los ajustes avanzados, establece Server URL en:

   http://localhost:3000/mcp

   Sin barra final. Cuando se define, Scalekit escribe esta URL en el claim aud del token de acceso junto con el id res_…. Si lo dejas vacío, aud solo es res_… — este ejemplo sigue verificando.

5. Guarda. Copia de la página del servidor:

   • Environment URL — https://<your-env>.scalekit.cloud

   • Resource ID — res_…

[!CAUTION] Si cambias el estado de DCR o CIMD más adelante, vuelve a conectar el cliente MCP. Inspector y otros clientes guardan en caché los metadatos del servidor de autorización. Este proceso no lo hace.

2. Configurar este repositorio

git clone git@github.com:scalekit-developers/scalekit-mcpuse-example.git
cd scalekit-mcpuse-example
npm install
cp .env.example .env

Edita .env con tus valores. No hay credenciales de ejemplo en este repositorio.

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.cloud
SCALEKIT_RESOURCE_ID=res_xxxxxxxx
MCP_URL=http://localhost:3000/mcp

No existe SCALEKIT_CLIENT_ID ni SCALEKIT_CLIENT_SECRET. El servidor de recursos solo verifica los tokens que Scalekit ya emitió.

3. Ejecutar e iniciar sesión

npm run dev

1. Abre Inspector.

2. Conéctate a http://localhost:3000/mcp. La primera llamada devuelve 401; Inspector inicia el inicio de sesión de Scalekit.

3. Completa el consentimiento en el navegador.

4. Llama a whoami.

Deberías ver un id usr_…, subjectType: "user", scopes como openid / profile, y:

{
  "iss": "https://your-env.scalekit.cloud",
  "aud": ["http://localhost:3000/mcp", "res_xxxxxxxx"]
}

iss también puede ser https://your-env.scalekit.cloud/resources/res_xxxxxxxx. Este ejemplo acepta ambos mientras Scalekit migra los valores del emisor.

Después llama a greet. El saludo usa ctx.auth.user.id del token verificado — ese es el patrón para limitar los datos de la herramienta por usuario.

Cómo funciona la verificación

oauth: oauthScalekitProvider({
  environmentUrl: process.env.SCALEKIT_ENVIRONMENT_URL!,
  resourceId: process.env.SCALEKIT_RESOURCE_ID!,
  resource: process.env.MCP_URL!,
}),

resourceId es el aud del JWT (res_…). resource es la URL pública del MCP. mcp-use pone resource en los metadatos de protected-resource de la RFC 9728. No es una segunda comprobación de audiencia.

resourceId es el límite de seguridad por servidor. Un token emitido para un servidor MCP distinto en el mismo entorno de Scalekit debe fallar.

La autorización se define junto a la herramienta:

async (_args, ctx) => {
  // ctx.auth.user.id is this caller — scope your data to it
  if (!ctx.auth.scopes.includes("todos:write")) {
    return { isError: true, content: [{ type: "text", text: "Missing scope" }] };
  }
};

oauth/scalekit.ts es un prototipo de un adaptador de primera clase mcp-use/oauth/scalekit. Todavía no está publicado en npm.

Estructura del proyecto

Cambiar la URL pública

Si expones el servidor (túnel, despliegue, host personalizado):

1. Establece Server URL en Scalekit a ese origen + /mcp (sin barra final).

2. Establece MCP_URL con la misma cadena.

3. Reinicia este proceso.

El verificador no cambia. resourceId sigue siendo la comprobación de audiencia.

Solución de problemas

Scalekit también publica una guía de solución de problemas de MCP auth.

Seguridad

• No pongas secretos de cliente, claves de API ni URLs de entorno personales en este repositorio.

• .env está en gitignore. Haz commit solo de .env.example.

• Este proceso nunca llama a Scalekit con un secreto de cliente. Solo verifica tokens de portador.

• MCP_USE_OAUTH_DEBUG=1 decodifica el payload del JWT para iss / aud / sub. No imprime el token.

Documentación

• Autentica un servidor mcp-use con Scalekit

• Guía de inicio rápido de Scalekit MCP Auth

• Descripción general de Scalekit MCP

• mcp-use

• Especificación de autorización de MCP