Zum Hauptinhalt springen

MCP Auth im MCP-Server konfigurieren

Mit der neuesten MCP-Spezifikation (2025-06-18) agiert dein MCP-Server als Ressourcenserver, der Zugangstokens (Zugangstoken) validiert, die von externen Autorisierungsservern ausgestellt wurden.

Um MCP Auth zu konfigurieren, sind zwei Hauptschritte erforderlich:

  1. Autorisierungsserver-Metadaten konfigurieren – Definiere, welche Autorisierungsserver gültige Tokens für deinen MCP-Server ausstellen dürfen und leite MCP-Clients an, wo sie Zugangstokens (Zugangstoken) erhalten können.
  2. Metadaten der geschützten Ressource konfigurieren – Definiere deinen MCP-Server als geschützte Ressource mit unterstützten Berechtigungen (Scopes).

Schritt 1: Autorisierungsserver-Metadaten konfigurieren​

Automatisches Abrufen von Metadaten​

Der einfachste Weg, Autorisierungsserver-Metadaten zu konfigurieren, ist die Verwendung der eingebauten Funktionen, die die Metadaten von bekannten URLs abrufen. Wenn dein Anbieter einem der folgenden Standards entspricht:

Kannst du fetchServerConfig verwenden, um die Metadaten automatisch abzurufen, indem du die issuer-URL angibst:

import { fetchServerConfig } from 'mcp-auth';

// Autorisierungsserver-Metadaten abrufen
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // oder 'oauth'

Wenn dein Aussteller (Issuer) einen Pfad enthält, unterscheidet sich das Verhalten leicht zwischen OAuth 2.0 und OpenID Connect:

  • OAuth 2.0: Die Well-known-URL wird an die Domain des Ausstellers angehängt. Zum Beispiel, wenn dein Aussteller https://my-project.logto.app/oauth ist, wird die Well-known-URL https://auth.logto.io/.well-known/oauth-authorization-server/oauth sein.
  • OpenID Connect: Die Well-known-URL wird direkt an den Aussteller angehängt. Zum Beispiel, wenn dein Aussteller https://my-project.logto.app/oidc ist, wird die Well-known-URL https://auth.logto.io/oidc/.well-known/openid-configuration sein.

On-Demand-Discovery​

Wenn du Edge-Runtimes wie Cloudflare Workers verwendest, bei denen asynchrones Fetch auf Top-Level nicht erlaubt ist, kannst du stattdessen On-Demand-Discovery nutzen. Gib einfach den issuer und type an, und die Metadaten werden automatisch beim ersten Bedarf abgerufen:

const authServerConfig = { issuer: '<issuer-url>', type: 'oidc' }; // oder 'oauth'

Weitere Möglichkeiten zur Konfiguration von Autorisierungsserver-Metadaten​

Benutzerdefinierte Daten-Transpilation​

In einigen Fällen entsprechen die vom Anbieter zurückgegebenen Metadaten möglicherweise nicht dem erwarteten Format. Wenn du sicher bist, dass der Anbieter konform ist, kannst du die Option transpileData verwenden, um die Metadaten vor der Verwendung zu modifizieren:

import { fetchServerConfig } from 'mcp-auth';

const authServerConfig = await fetchServerConfig('<auth-server-issuer>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Damit kannst du das Metadatenobjekt vor der Verwendung durch MCP Auth anpassen. Zum Beispiel kannst du Felder hinzufügen oder entfernen, deren Werte ändern oder sie in ein anderes Format umwandeln.

Metadaten von einer bestimmten URL abrufen​

Wenn dein Anbieter eine bestimmte Metadaten-URL anstelle der Standard-URLs hat, kannst du diese ähnlich verwenden:

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', { type: 'oidc' }); // oder 'oauth'

Metadaten von einer bestimmten URL mit benutzerdefinierter Daten-Transpilation abrufen​

In manchen Fällen kann die Antwort des Anbieters fehlerhaft oder nicht dem erwarteten Metadatenformat entsprechend sein. Wenn du sicher bist, dass der Anbieter konform ist, kannst du die Metadaten über die Konfigurationsoption transpiliert bereitstellen:

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Metadaten manuell bereitstellen​

Wenn dein Anbieter kein Metadaten-Fetching unterstützt, kannst du das Metadatenobjekt manuell bereitstellen:

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // Metadatenfelder sollten camelCase sein
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... weitere Metadatenfelder
  },
  type: 'oidc', // oder 'oauth'
};

Schritt 2: Metadaten der geschützten Ressource konfigurieren​

Nachdem du die Autorisierungsserver-Metadaten konfiguriert hast, musst du MCPAuth als Ressourcenserver initialisieren, indem du die Metadaten deiner geschützten Ressourcen definierst.

Dieser Schritt folgt der RFC 9728 (OAuth 2.0 Protected Resource Metadata) Spezifikation, um deinen MCP-Server als geschützte Ressource zu beschreiben:

import { MCPAuth } from 'mcp-auth';

// Definiere deinen Ressourcenbezeichner
const resourceIdentifier = 'https://api.example.com/notes';

// Initialisiere MCPAuth im Ressourcenserver-Modus
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig], // Verwendung der Konfiguration aus Schritt 1
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Für mehrere Ressourcen kannst du ein Array von Konfigurationen für geschützte Ressourcen bereitstellen, jeweils mit eigener Metadatenkonfiguration.

Die oben gezeigte Konfiguration deckt das grundlegende Setup ab. Für weiterführende Metadaten-Parameter siehe RFC 9728.

Schritt 3: Endpoint für Metadaten der geschützten Ressource bereitstellen​

Binde den Router ein, um den Endpoint für die Metadaten der geschützten Ressource bereitzustellen. Der Pfad des Endpoints wird automatisch durch die Pfadkomponente deines Ressourcenbezeichners bestimmt:

  • Kein Pfad: https://api.example.com → /.well-known/oauth-protected-resource
  • Mit Pfad: https://api.example.com/notes → /.well-known/oauth-protected-resource/notes
import express from 'express';

const app = express();

const mcpAuth = new MCPAuth({/* ... */});

app.use(mcpAuth.protectedResourceMetadataRouter());