mcp-use + Scalekit MCP Auth

Ein mcp-use MCP-Server, der sich mit Scalekit OAuth 2.1 authentifiziert.

Teammitglieder teilen sich eine Server-URL. Jede Person meldet sich an. Die Tools sehen ihre Identität (ctx.auth.user.id), nicht einen gemeinsamen API-Schlüssel.

Dieses Beispiel verwendet kein @scalekit-sdk/node und benötigt keine Scalekit-Client-ID und kein Client-Secret. Der Ressourcen-Server verifiziert JWTs gegen die Scalekit-JWKS.

Die Anleitung im Kochbuch-Stil findest du in docs/v2/typescript/server/authentication/providers/scalekit.mdx. Diese README ist das Runbook für dieses Repository.

[!IMPORTANT] Verwende deine eigene Scalekit-Umgebung. Dieses Repository enthält nur Platzhalter. .env niemals committen.

Was du bekommst

• Streamable HTTP MCP unter /mcp

• 401 + WWW-Authenticate, das auf RFC-9728-Metadaten der geschützten Ressource verweist

• Scalekit als Autorisierungsserver (DCR und CIMD)

• whoami — angemeldeter Benutzer, Scopes und iss / aud des Tokens

• greet — ein Tool, das auf ctx.auth.user.id basiert

Related MCP server: Access Self-Hosted MCP Server

Wie sich ein Client anmeldet

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

Voraussetzungen

• Node.js 22.22.2 oder neuer

• Ein Scalekit-Konto (Registrieren, falls du noch keines hast)

• Mindestens eine aktivierte Authentifizierungsmethode (Google, GitHub, passwortlos oder Enterprise-SSO)

1. Einen MCP-Server in Scalekit registrieren

Folge dem MCP Auth Quickstart mit diesen Werten:

1. Öffne das Scalekit-Dashboard → MCP-Server → MCP-Server hinzufügen.

2. Vergib einen Namen. Dieser Name erscheint auf dem Zustimmungsbildschirm (Consent Screen).

3. Aktiviere Dynamic Client Registration und Client ID Metadata Document (CIMD). Öffentliche Clients wie Inspector, Claude und Cursor benötigen mindestens eine davon; lasse beide aktiviert.

4. Lege unter Erweiterte Einstellungen die Server-URL fest:

http://localhost:3000/mcp

Kein abschließender Schrägstrich. Wenn gesetzt, schreibt Scalekit diese URL in den aud-Claim des Access-Tokens, zusätzlich zur res_…-ID. Wenn du die URL leer lässt, enthält aud nur res_… – dieses Beispiel verifiziert trotzdem.

5. Speichere. Kopiere von der Serverseite:

   • Umgebungs-URL – https://<your-env>.scalekit.cloud

   • Ressourcen-ID – res_…

[!CAUTION] Wenn du DCR oder CIMD später umschaltest, verbinde den MCP-Client neu. Inspector und andere Clients speichern die Metadaten des Autorisierungsservers im/at. Dieser Prozess tut das nicht.

2. Dieses Repository einrichten

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

Bearbeite .env mit deinen Werten. In diesem Repository gibt es keine Beispiel-Zugangsdaten.

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

Es gibt keine SCALEKIT_CLIENT_ID oder SCALEKIT_CLIENT_SECRET. Der Ressourcen-Server verifiziert ausschließlich angewackelthat –Token, die Scalekit bereits ausgestellt hat.

3. Starten und anmelden

npm run dev

1. Öffne Inspector.

2. Verbinde dich mit http://localhost:3000/mcp. Der erste Aufruf liefert 401; Inspector startet den Scalekit-Login.

3. Schließe die Zustimmung im Browser ab.

4. Rufe whoami auf.

Du solltest eine usr_…-ID, subjectType: "user", Scopes wie openid / profile und Folgendes sehen:

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

iss kann auch https://your-env.scalekit.cloud/resources/res_xxxxxxxx sein. Dieses Beispiel akzeptiert beide Varianten, während Scalekit die Issuer-Werte migriert.

Rufe dann greet auf. Die Begrüßung verwendet ctx.auth.user.id aus dem verifizierten Token – das ist das Muster, um Tool-Daten pro Benutzer einzuschränken.

Wie die Verifizierung funktioniert

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

resourceId ist die JWT-aud (res_…). resource ist die öffentliche MCP-URL. mcp-use setzt resource in die RFC-9728-Metadaten der geschützten Ressource. Es ist keine zweite Audience-Prüfung.

resourceId ist die Sicherheitsgrenze pro Server. Ein Token, das für einen anderen MCP-Server in derselben Scalekit-Umgebung ausgestellt wurde, muss fehlschlagen.

Die Autorisierung gehört direkt neben das Tool:

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 ist ein Prototyp eines erstklassigen mcp-use/oauth/scalekit-Adapters. Er ist noch nicht auf npm veröffentlicht.

Projektstruktur

Öffentliche URL ändern

Wenn du den Server öffentlich erreichbar machst (Tunnel, Deployment, eigener Host):

1. Setze die Server-URL in Scalekit auf die Origin + /mcp (ohne abschließenden Schrägstrich).

2. Setze MCP_URL auf denselben String.

3. Starte diesen Prozess neu.

Der Verifizierer ändert sich nicht. resourceId bleibt die Audience-Prüfung.

Fehlerbehandlung

Security

• Set MCP_USE_OAUTH_DEBUG=1 und versuche es erneut. Logs geben iss, aud und sub aus – niemals das rohe Token.

Scalekit veröffentlicht auch einen Leitfaden zur MCP-Auth-Fehlerbehandlung.

Dokumentation

• Keine Client-Secrets, API-Keys oder persönlichen Umgebungs-URLs in dieses Repository legen.

• .env ist gitignored. Committe nur .env.example.

• Dieser Prozess ruft Scalekit immer um der Client–Secret; er prüft ausschließlich Bearer-Tokens.

Siehe

• Einen mcp-use-Server mit Scalekit authentifizieren

• Scalekit MCP Auth quickstart

• Scalekit MCP overview

• mcp-use

• MCP authorization specification

• [Security – a README][] ergänzt not mehr, siehe TLS.

Testen

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" }] };
  }
};