Zum Hauptinhalt springen

Erste Schritte

MCP-Autorisierungsspezifikation unterstützt

Diese Version unterstützt die MCP-Autorisierungsspezifikation (Version 2025-06-18).

Python SDK verfügbar

MCP Auth ist auch für Python verfügbar! Schau dir das Python SDK Repository für Installation und Nutzung an.

Wähle einen kompatiblen OAuth 2.1- oder OpenID Connect-Anbieter​

Die MCP-Spezifikation hat spezifische Anforderungen für die Autorisierung. Der Autorisierungsmechanismus basiert auf etablierten Spezifikationen und implementiert eine ausgewählte Teilmenge ihrer Funktionen, um Sicherheit und Interoperabilität bei gleichzeitiger Einfachheit zu gewährleisten:

Diese Spezifikationen arbeiten zusammen, um einen sicheren und standardisierten Autorisierungsrahmen für MCP-Implementierungen bereitzustellen.

Du kannst die Liste MCP-kompatibler Anbieter prüfen, um zu sehen, ob dein Anbieter unterstützt wird.

Installiere das MCP Auth SDK​

pnpm add mcp-auth

Initialisiere MCP Auth​

Der erste Schritt ist, deinen Ressourcenbezeichner zu definieren und den Autorisierungsserver zu konfigurieren, dem für die Authentifizierung vertraut wird. MCP Auth arbeitet jetzt im Resource-Server-Modus und entspricht der aktualisierten MCP-Spezifikation, die OAuth 2.0 Protected Resource Metadata (RFC 9728) erfordert.

Wenn dein Anbieter konform ist mit:

kannst du die eingebaute Funktion nutzen, um die Metadaten abzurufen und die MCP Auth-Instanz zu initialisieren:

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

// 1. Definiere deinen Ressourcenbezeichner und hole die Konfiguration für den vertrauenswürdigen Autorisierungsserver.
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. Initialisiere MCPAuth im Resource-Server-Modus.
// `protectedResources` kann ein einzelnes Objekt oder ein Array für mehrere Ressourcen sein.
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Wenn du Edge-Runtimes wie Cloudflare Workers verwendest, bei denen asynchrones Fetch auf Top-Level nicht erlaubt ist, verwende stattdessen On-Demand-Discovery:

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

Für weitere Möglichkeiten zur Konfiguration der Autorisierungsserver-Metadaten, einschließlich benutzerdefinierter Metadaten-URLs, Daten-Transpilation oder manueller Metadatenspezifikation, siehe Weitere Möglichkeiten zur Konfiguration von MCP Auth.

Binde den Protected Resource Metadata Endpoint ein​

Um der aktualisierten MCP-Spezifikation zu entsprechen, bindet MCP Auth den OAuth 2.0 Protected Resource Metadata Endpoint (RFC 9728) in deinen MCP-Server ein. Dieser Endpoint ermöglicht es Clients, zu entdecken:

  • Welche Autorisierungsserver gültige Tokens für deine geschützten Ressourcen ausstellen können
  • Welche Berechtigungen (Scopes) für jede Ressource unterstützt werden
  • Weitere Metadaten, die für die korrekte Token-Validierung erforderlich sind

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

Der MCP-Server dient nun als Resource-Server, der Tokens validiert und Metadaten über seine geschützten Ressourcen bereitstellt, während er sich vollständig auf externe Autorisierungsserver für Authentifizierung und Autorisierung verlässt.

Du kannst die bereitgestellte Methode des SDK verwenden, um diesen Endpoint einzubinden:

import express from 'express';

const app = express();

// Binde den Router ein, um die Protected Resource Metadata bereitzustellen.
// Für Ressource "https://api.example.com" → Endpoint: /.well-known/oauth-protected-resource
// Für Ressource "https://api.example.com/notes" → Endpoint: /.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

Verwende das Bearer-Auth-Middleware​

Sobald die MCP Auth-Instanz initialisiert ist, kannst du das Bearer-Auth-Middleware anwenden, um deine MCP-Routen zu schützen. Das Middleware erfordert nun die Angabe, zu welcher Ressource der Endpoint gehört, um eine korrekte Token-Validierung zu ermöglichen:

Audience-Validierung

Der audience-Parameter ist erforderlich gemäß der OAuth 2.0-Spezifikation für eine sichere Token-Validierung. Er ist jedoch derzeit optional, um die Kompatibilität mit Autorisierungsservern zu gewährleisten, die noch keine Ressourcenbezeichner unterstützen. Aus Sicherheitsgründen bitte immer den audience-Parameter angeben, wenn möglich. Zukünftige Versionen werden die Audience-Validierung verpflichtend machen, um die Spezifikation vollständig zu erfüllen.

Immer Berechtigungen (Scopes) validieren

In OAuth 2.0 sind Berechtigungen (Scopes) der primäre Mechanismus zur Berechtigungssteuerung. Ein gültiges Token mit der richtigen audience garantiert NICHT, dass der Benutzer die Berechtigung hat, eine Aktion auszuführen — Autorisierungsserver können Tokens mit leerer oder eingeschränkter Berechtigung ausstellen.

Verwende immer requiredScopes, um sicherzustellen, dass das Token die notwendigen Berechtigungen für jede Operation enthält. Gehe niemals davon aus, dass ein gültiges Token vollen Zugriff impliziert.

import express from 'express';

const app = express();

// Binde den Router ein, um die Protected Resource Metadata bereitzustellen.
app.use(mcpAuth.protectedResourceMetadataRouter());

// Schütze einen API-Endpoint mit der ressourcenspezifischen Policy.
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // Aktiviere Audience-Validierung für Sicherheit
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // Wenn das Token gültig ist, wird `req.auth` mit seinen Ansprüchen befüllt.
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

In den obigen Beispielen geben wir den Token-Typ jwt und den Ressourcenbezeichner an. Das Middleware validiert das JWT-Token automatisch gegen die vertrauenswürdigen Autorisierungsserver, die für diese spezifische Ressource konfiguriert sind, und befüllt die Informationen des authentifizierten Benutzers.

info

Noch nie von JWT (JSON Web Token) gehört? Keine Sorge, du kannst die Dokumentation weiter lesen und wir erklären es, wenn es nötig ist. Du kannst auch das Auth Wiki für eine kurze Einführung besuchen.

Weitere Informationen zur Bearer-Auth-Konfiguration findest du unter Bearer-Auth konfigurieren.

Auth-Info in deiner MCP-Implementierung abrufen​

Sobald das Bearer-Auth-Middleware angewendet ist, kannst du auf die Informationen des authentifizierten Benutzers (oder der Identität) in deiner MCP-Implementierung zugreifen:

Das zweite Argument des Tool-Handlers enthält das authInfo-Objekt, das die Informationen des authentifizierten Benutzers enthält:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// Initialisiere mit MCP Auth wie in den vorherigen Beispielen gezeigt
// ...

server.registerTool(
  'add',
  {
    description: 'Addiere zwei Zahlen',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // Jetzt kannst du das `authInfo`-Objekt verwenden, um auf die authentifizierten Informationen zuzugreifen
  }
);

Nächste Schritte​

Lies weiter, um ein End-to-End-Beispiel zu erfahren, wie du MCP Auth in deinen MCP-Server integrierst und wie du den Auth-Flow in MCP-Clients handhabst.