Zum Hauptinhalt springen

Authentifizierung für deine MCP-basierten Apps mit Logto aktivieren

tipp:

Entdecke Logtos KI-Lösungen: Authentifizierung (Authentication) und Autorisierung (Authorization) für MCP-Server, KI-Agenten und Apps.

Diese Anleitung führt dich durch die Integration von Logto mit deinem MCP-Server unter Verwendung von mcp-auth und dem offiziellen MCP SDK v2. So kannst du Benutzer authentifizieren und ihre verifizierte Identität sicher aus dem Zugangstoken auslesen.

Du lernst, wie du:

  • Logto als Autorisierungsserver für deinen MCP-Server konfigurierst.
  • Ein „whoami“-Tool in deinem MCP-Server einrichtest, das die Identitätsansprüche des aktuellen Benutzers zurückgibt.
  • Den Ablauf mit VS Code (MCP-Client) testest.

Nach diesem Tutorial wird dein MCP-Server:

  • Benutzer in deinem Logto-Mandanten authentifizieren.
  • JWT-Zugangstokens, die von Logto ausgestellt wurden, verifizieren (Signatur, Aussteller, Zielgruppe und Ablauf).
  • Die verifizierten Identitätsansprüche (sub, iss, aud usw.) für den Aufruf des "whoami"-Tools zurückgeben.

Sobald die Integration abgeschlossen ist, kannst du VS Code durch deinen eigenen MCP-Client, wie z. B. eine Webanwendung, ersetzen, um auf die vom MCP-Server bereitgestellten Tools und Ressourcen zuzugreifen.

Beispielcode:

Den vollständigen, lauffähigen Beispielcode für diese Anleitung findest du im mcp-auth/js Repository:

  • whoami-express: Der "whoami"-Server in dieser Anleitung, auf Node.js mit Express.
  • whoami: Derselbe Server, gebaut mit fetch-native (web-standard Request / Response mit Hono), bereitstellbar auf Cloudflare Workers.

Voraussetzungen​

  • Ein Logto Cloud (oder selbst gehosteter) Mandant
  • Node.js >= 20 Umgebung

Architektur verstehen​

  • MCP-Server: Der Server, der Tools und Ressourcen für MCP-Clients bereitstellt. Nach der neuesten MCP-Spezifikation agiert er als OAuth 2.0-Ressourcenserver, der Zugangstokens (Access tokens) validiert, die von Logto ausgestellt wurden.
  • MCP-Client: Ein Client, der verwendet wird, um den Authentifizierungsablauf zu starten und die Integration zu testen. Wir verwenden VS Code (mit integrierter MCP-Unterstützung) als Client in dieser Anleitung.
  • Logto: Dient als OpenID Connect-Provider (Autorisierungsserver), verwaltet Benutzeridentitäten und stellt zielgruppenbezogene JWT-Zugangstokens (Access tokens) für deinen MCP-Server aus.

Ein nicht-normativer Sequenzdiagramm veranschaulicht den Gesamtablauf des Prozesses:

hinweis:

Da sich MCP schnell weiterentwickelt, ist das obige Diagramm möglicherweise nicht vollständig aktuell. Bitte schaue in die mcp-auth-Dokumentation für die neuesten Informationen.

App in Logto einrichten​

Dein MCP-Client muss als Anwendung in Logto registriert werden, um den Autorisierungsablauf zu starten. In dieser Anleitung registrieren wir VS Code als Client:

  1. Melde dich bei deiner Logto-Konsole an.

  2. Gehe zu Anwendungen → Anwendung erstellen → App ohne Framework erstellen.

  3. Wähle den Typ: Native App.

  4. Gib den App-Namen ein (z. B. „VS Code“) und fülle die weiteren erforderlichen Felder aus, dann klicke auf Anwendung erstellen.

  5. Füge im Bereich Einstellungen / Redirect-URIs die folgenden Redirect-URIs für VS Code hinzu und speichere die Änderungen:

    http://127.0.0.1
    https://vscode.dev/redirect

  6. Speichere und kopiere die App-ID und den Aussteller-Endpunkt.

MCP-Server einrichten​

Wir verwenden das offizielle MCP SDK v2 und mcp-auth, um einen MCP-Server mit einem "whoami"-Tool zu erstellen, das die Identitätsansprüche des aktuellen Benutzers zurückgibt.

Projekt erstellen und Abhängigkeiten installieren​

mkdir mcp-server
cd mcp-server
npm init -y
npm pkg set type="module"
npm pkg set main="whoami.js"
npm pkg set scripts.start="node whoami.js"
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mcp-auth
  • @modelcontextprotocol/server ist das Kern-MCP SDK v2, das web-standardisierte Request / Response spricht.
  • @modelcontextprotocol/express und @modelcontextprotocol/node passen es an Express auf Node.js an.
  • mcp-auth liefert den Token-Verifizierer und die OAuth-Discovery-Metadaten für das MCP SDK.
hinweis:

Das MCP SDK v2 und mcp-auth sind ausschließlich ESM und erfordern Node.js >= 20.

Den MCP-Server als API-Ressource registrieren​

Die aktuelle MCP-Spezifikation verlangt, dass Zugangstokens (Access tokens) an die Ressource gebunden sind, für die sie ausgestellt wurden (RFC 8707), und mcp-auth erzwingt dies: Der aud-Anspruch (Claim) des Tokens muss mit dem Ressourcenindikator deines MCP-Servers übereinstimmen. In Logto geschieht dies, indem du eine API-Ressource erstellst, deren Indikator mit der URL deines MCP-Servers übereinstimmt:

  1. Melde dich bei deiner Logto-Konsole an.
  2. Gehe zu API-Ressourcen → API-Ressource erstellen.
  3. Fülle die Details aus und klicke dann auf API-Ressource erstellen:
    • API-Name: Gib einen Namen ein, z. B. "Who am I".
    • API-Indikator: Gib http://localhost:3001/ ein. Er muss mit dem Ressourcenindikator übereinstimmen, den wir im MCP-Server konfigurieren.
Abschließender Schrägstrich im Ressourcenindikator:

Füge immer einen abschließenden Schrägstrich (/) im Ressourcenindikator hinzu. Aufgrund eines aktuellen Fehlers im offiziellen MCP SDK fügen Clients, die das SDK verwenden, beim Starten von Authentifizierungsanfragen automatisch einen abschließenden Schrägstrich zu Ressourcenindikatoren hinzu. Wenn dein Ressourcenindikator keinen abschließenden Schrägstrich enthält, schlägt die Ressourcenvalidierung für diese Clients fehl.

MCP Auth mit Logto konfigurieren​

Deklariere deinen MCP-Server als geschützte Ressource: seinen Ressourcenindikator und den Autorisierungsserver, dem er vertraut. Ersetze <your-logto-issuer-endpoint> durch den zuvor kopierten Aussteller-Endpunkt (zu finden auf der Anwendungsdetailseite unter Endpoints & Credentials, z. B. https://my-project.logto.app/oidc).

In whoami.js:

import { MCPAuth } from 'mcp-auth';

const authIssuer = '<your-logto-issuer-endpoint>';

const mcpAuth = new MCPAuth({
  protectedResourceMetadata: {
    // Der Ressourcenindikator; muss mit dem in Logto registrierten API-Ressourcenindikator übereinstimmen
    resource: 'http://localhost:3001/',
    // Der von diesem MCP-Server vertraute Autorisierungsserver
    authorizationServer: { issuer: authIssuer, type: 'oidc' },
  },
});

Die Metadaten des Autorisierungsservers werden bei Bedarf lazy geladen und anschließend zwischengespeichert. Die MCPAuth-Instanz überprüft JWT-Zugangstokens (Access tokens) anhand von Logtos JWKS — Signatur, Aussteller (Issuer), Zielgruppe (Audience) und Ablauf werden alle durchgesetzt. Eine handgeschriebene Token-Überprüfung ist nicht erforderlich.

Das "whoami"-Tool implementieren​

Nun implementieren wir das "whoami"-Tool, das die Identitätsansprüche des aktuellen Benutzers aus dem verifizierten Zugangstoken zurückgibt. Verwende getAuthInfo, um die von mcp-auth verifizierten Authentifizierungsinformationen aus dem Callback-Kontext des Tools auszulesen.

import { McpServer } from '@modelcontextprotocol/server';
import { getAuthInfo } from 'mcp-auth';

// Fabrikfunktion zum Erstellen einer MCP-Serverinstanz
// Jede Anfrage erhält ihre eigene Serverinstanz, um Anfragen zu isolieren
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'WhoAmI',
    version: '0.0.0',
  });

  // Füge dem Server ein Tool hinzu, das die Informationen des aktuellen Benutzers zurückgibt
  mcpServer.registerTool(
    'whoami',
    {
      description: 'Hole die Informationen des aktuellen Benutzers',
    },
    (context) => {
      const { claims } = getAuthInfo(context);
      return {
        content: [{ type: 'text', text: JSON.stringify(claims) }],
      };
    }
  );

  return mcpServer;
};

Den Server verbinden​

Zum Schluss stelle die OAuth-Discovery-Dokumente (RFC 9728 / RFC 8414) bereit, damit MCP-Clients deinen Autorisierungsserver finden können, und schütze den MCP-Endpunkt mit der Bearer-Auth-Middleware des SDKs.

import {
  createMcpExpressApp,
  mcpAuthMetadataRouter,
  requireBearerAuth,
} from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';

const PORT = 3001;

// Der MCP-Handler spricht web-standardisiertes Request / Response; `toNodeHandler` passt ihn an Express an
const mcpNodeHandler = toNodeHandler(createMcpHandler(createMcpServer));

const app = createMcpExpressApp();

// Stelle die OAuth-Discovery-Dokumente (`/.well-known/...`) bereit, standardmäßig öffentlich
app.use(mcpAuthMetadataRouter(await mcpAuth.getAuthMetadataOptions()));

app.all(
  '/',
  // Erfordert ein gültiges Bearer-Token; die verifizierten Authentifizierungsinformationen werden über `req.auth` an den Handler weitergegeben
  requireBearerAuth(mcpAuth.getBearerAuthOptions()),
  // `createMcpExpressApp` verwendet `express.json()`, wodurch der Request-Stream geleert wird, daher wird der
  // geparste Body explizit weitergegeben
  async (request, response) => mcpNodeHandler(request, response, request.body)
);

app.listen(PORT);

Starte den Server mit:

npm start

Integration testen​

  1. Starte den MCP-Server:

    npm start

  2. Verbinde VS Code mit deinem MCP-Server:

    1. Drücke Command + Shift + P (macOS) oder Ctrl + Shift + P (Windows / Linux), um die Befehlspalette zu öffnen.
    2. Tippe MCP: Add Server... und wähle es aus.
    3. Wähle HTTP als Servertyp.
    4. Gib die MCP-Server-URL ein: http://localhost:3001/
    5. Wenn der OAuth-Ablauf startet, fordert VS Code die Client-ID an: Füge die zuvor kopierte App-ID ein.
    6. Da es sich um einen öffentlichen Client ohne App-Secret handelt, drücke einfach Enter, um das Secret zu überspringen.
    7. Schließe den Anmeldeablauf in deinem Browser ab.

  3. Nach der Anmeldung führe das whoami-Tool in VS Code aus.

Du solltest die verifizierten Ansprüche aus dem Zugangstoken sehen, wie zum Beispiel:

{
  "iss": "https://my-project.logto.app/oidc",
  "sub": "user_XXXX",
  "aud": "http://localhost:3001/",
  "client_id": "<your-app-id>"
}

Weiterführende Informationen​

Dein MCP-Server verifiziert jetzt eingehende Zugangstokens. Als nächsten Schritt erfährst du, wie er im Namen der Benutzer sicher deine nachgelagerten Business-APIs aufrufen kann – ohne Token-Durchleitung oder Verlust des Benutzerkontexts:

Wie ein MCP-Server deine API im Namen der Benutzer aufruft: eine produktionsreife Token-Strategie