MCP OAuth 2.1 mit PKCE: Sichern Sie Ihren Agent-Server in 7 Schritten

Die MCP-Spezifikation vom 15.03.2026 sperrt OAuth 2.1 mit PKCE als Autorisierungsstandard für Remote-MCP-Server. API-Schlüssel in Umgebungsvariablen funktionieren noch am ersten Tag, aber die Registrierung, Claude Desktop, Cursor, VS Code Copilot und Windsurf bevorzugen als Benutzer alle OAuth-gestützte Server Suchen Sie nach Integrationen. Wenn Ihr Server in einer Konfigurationsdatei immer noch nach einem langlebigen Träger fragt, können Sie lassen einen Teil der Verteilung auf dem Tisch.

Der schwierige Teil ist nicht OAuth selbst; Es sind die fünf kleinen Spezifikationen, die der MCP-Authentifizierungsfluss zusammensetzt zusammen: OAuth 2.1 (RFC 9700), PKCE (RFC 7636), Dynamic Client Registration (RFC 7591), Ressourcenindikatoren (RFC 8707) und geschützte Ressourcenmetadaten. Jeder ist klein; die Verkabelung Hier bleiben Teams stecken. Hier ist der Pfad in der richtigen Reihenfolge.

Schritt 1: Bereitstellen eines Metadatendokuments für geschützte Ressourcen

Die PRM-Datei teilt Clients mit, wo sich Ihr Autorisierungsserver befindet, welche Bereiche Sie akzeptieren und was Ressourcen-ID, die eingefügt werden soll aud beanspruchen. Hosten Sie es unter /.well-known/oauth-protected-resource auf demselben Ursprung wie Ihr MCP-Endpunkt:

Der authorization_servers list ist der Discovery-Hop. Kunden holen Ihr PRM ab, Folgen Sie dem ersten Eintrag zum AS-Metadatendokument und erstellen Sie von dort aus die Autorisierungs-URL. Beschränken Sie die Liste auf einen Eintrag, es sei denn, Sie leiten eine Föderation. Mehrere Emittenten verwirren den Kunden und Nichts in der Spezifikation erfordert dies.

Schritt 2: Veröffentlichen Sie die Metadaten des Autorisierungsservers

Ihr Identitätsanbieter (Auth0, Okta, Clerk, Cloudflare Access oder eine selbst gehostete Hydra) dient die AS-Metadaten unter /.well-known/oauth-authorization-server. MCP-Clients konsumieren es um die Autorisierungs- und Token-Endpunkte, die unterstützten Gewährungstypen und den JWKS-Standort zu erfahren zur Token-Verifizierung:

Drei Felder fordert die Spezifikation: code_challenge_methods_supported muss beinhalten S256; grant_types_supported muss beinhalten authorization_code Und refresh_token; registration_endpoint muss vorhanden sein, wenn Sie dynamische Clients unterstützen. Vermisse irgendjemanden und Claude Desktop markiert den Server während der Einrichtung als nicht konform.

Schritt 3: Generieren Sie ein PKCE-Paar auf dem Client

PKCE besteht aus 20 Zeilen Client-Code und tötet die Authorization-Code-Interception-Klasse von Angriff. Generieren Sie 32 zufällige Bytes und kodieren Sie sie mit Base64URL in einen Verifizierer, den Verifizierer SHA-256 in eine Challenge ein und senden Sie die Challenge mit der Autorisierungsanfrage:

Der resource Der Parameter (RFC 8707) ist der, den die meisten Implementierungen vermissen. Ohne Damit kann ein für Ihren MCP-Server geprägtes Token gegen jede andere API abgespielt werden, die diesem vertraut gleicher Emittent; damit, die aud Claim heftet das Token an Ihre Ressourcenkennung und nichts anderes akzeptiert es.

Schritt 4: Tauschen Sie den Code gegen Tokens ein

Nach der Rückumleitung sendet der Client den Code und den ursprünglichen Verifizierer per POST an das Token Endpunkt. Der Autorisierungsserver berechnet den SHA-256 des Verifizierers neu und vergleicht ihn damit die gespeicherte Herausforderung; Wenn sie übereinstimmen, erhalten Sie ein Zugriffstoken:

Speichern Sie das Aktualisierungstoken in einem sicheren Speicher (Schlüsselbund, Windows Credential Manager, Linux). libsecret) und löschen Sie den Verifizierer aus dem Sitzungsspeicher, sobald der Austausch erfolgreich ist. Zugang Token haben eine Lebensdauer von 5 bis 60 Minuten; Aktualisierungstoken sind länger gültig, sollten aber bei Verwendung trotzdem rotieren.

Schritt 5: Überprüfen Sie das Bearer-Token bei jeder MCP-Anfrage

Streamable HTTP macht die Token-Verifizierung einfach: Jede HTTP-Anfrage trägt das Authorization Header, sodass Ihr MCP-Server ihn zuvor in der Middleware überprüft Versenden des Tool-Aufrufs. Rufen Sie das JWKS einmal ab, speichern Sie es im Cache und validieren Sie Aussteller, Zielgruppe usw Ablauf bei jedem Anruf:

Die drei Behauptungen, die echte Fehler aufdecken: iss steckt den Emittenten fest; aud fixiert die Ressource (verhindert ressourcenübergreifende Wiedergabe); exp fängt veraltete Token ab. Akzeptieren Sie keine Token ohne diese; „Ich habe das validiert „Unterschrift“ ist nicht dasselbe wie „Ich habe die Ansprüche bestätigt.“

Schritt 6: Ordnen Sie jedes Werkzeug den Bereichen zu, die seine Anmerkungen deklarieren

OAuth 2.1 ohne Scope-Design bietet Ihnen binären Zugriff: Entweder kann der Client jedes Tool aufrufen oder keine. Das MCP-Annotationssystem schließt diese Lücke, indem es jedem Tool ermöglicht, seinen Geltungsbereich zu deklarieren Bedürfnisse. Der Handler liest die Anmerkungen und die Token-Bereiche zum Zeitpunkt des Aufrufs:

Halten Sie destruktive und schreibgeschützte Bereiche getrennt. Ein Benutzer, der gewährt hat tools:read zu Das Ausführen eines wöchentlichen Berichts sollte nicht möglich sein send_email aus demselben Token. Claude Desktop und Cursoroberfläche haben im Zustimmungsbildschirm die angeforderten Bereiche angezeigt, sodass die Aufteilung erfolgt Die UX ist ehrlich darüber, was der Kunde tun kann.

Schritt 7: Unterstützen Sie die dynamische Client-Registrierung

Durch die dynamische Clientregistrierung kann sich ein MCP-Client selbst bei Ihrem Autorisierungsserver registrieren ohne dass ein Mensch ein Formular ausfüllt. Cursor oder Claude Desktop sendet eine Registrierungsanfrage, erhält eine client_idund führt den OAuth-Flow sofort aus:

Dies ist der Teil, der Ihren MCP-Server von „Einfügen eines API-Schlüssels in eine Konfigurationsdatei“ auf „Einfügen eines API-Schlüssels in eine Konfigurationsdatei“ umstellt „Klicken Sie im Cursor auf „Verbinden“ und gewähren Sie Zugriff.“ Die Arbeit lohnt sich, wenn Ihr Server öffentlich ist. überspringbar wenn Sie nur an eine kleine Gruppe bekannter Kunden versenden.

Überprüfen Sie den gesamten Fluss von Ende zu Ende

Sobald die Teile vorhanden sind, sieht ein vollständiger MCP-Tool-Aufruf wie jeder andere trägerauthentifizierte Aufruf aus HTTP-Anfrage:

Wenn Sie sehen 401 mit WWW-Authenticate: Bearer resource_metadata="...", Der Client weiß, wo er Ihr Authentifizierungs-Setup finden und den Ablauf erneut ausführen kann. Dieser Header ist der Handshake, der eine stille Token-Aktualisierung und erneute Verbindung nach einem Widerruf ermöglicht.

Spickzettel für Scope-Design

Wichtige Erkenntnisse

• OAuth 2.1 erfordert PKCE. Kein Nice-to-have; Jeder Authentifizierungscodefluss trägt a Verifizierer und Herausforderung, oder die Spezifikationskonformität wird nicht eingehalten.
• PRM bei /.well-known/oauth-protected-resource ist der Einstiegspunkt. Kunden entdecken Ihr Authentifizierungs-Setup über diese eine URL. Überspringen Sie es und Clients können sich nicht automatisch konfigurieren.
• Benutzen Sie die resource Parameter (RFC 8707). Pinnt das Token-Publikum an Ihren MCP-Server, sodass ein durchgesickertes Token nicht gegen andere APIs wiedergegeben werden kann.
• Validieren Sie Emittenten, Zielgruppe, Ablauf und Geltungsbereich. Allein Unterschriftsschecks lassen zu Ressourcenübergreifende Wiedergabe.
• Zerstörerische Bereiche aufteilen. tools:read, tools:invoke:safe, Und tools:invoke:destructive Geben Sie Benutzern die Zustimmung UX, die sie von Betriebssystemberechtigungen erwarten.
• Durch die dynamische Client-Registrierung werden Zero-Config-Installationen freigeschaltet. Zahlen Sie die Implementierungskosten einmalig; Jeder neue MCP-Kunde profitiert für immer.

Botois gehosteter MCP-Server unter api.botoi.com/mcp läuft nach dem gleichen Muster ab. Durchsuchen Sie die MCP-Setup-Dokumente für Claude Desktop-, Claude Code-, Cursor-, VS Code- und Windsurf-Konfigurationen. Für die JWT-Signatur und Verifizierungsprimitive, die die obige Middleware verwendet, finden Sie unter JWT-API-Endpunkte in den interaktiven Dokumenten.