HTTP OAuth MCP Server

🌊 HTTP + SSE MCP-Server mit OAuth

Einführung

Dieses Repo bietet eine Referenzimplementierung zum Erstellen eines Remote-MCP-Servers, der die streambaren HTTP- und SSE-Transporte unterstützt und mit OAuth basierend auf der MCP-Spezifikation autorisiert ist.

Beachten Sie, dass der MCP-Server in diesem Repo logisch von der Anwendung, die die SSE- und HTTP-Transporte des Berichts verarbeitet, und von OAuth getrennt ist.

Daher können Sie dieses Repo problemlos forken und Ihren eigenen MCP-Server und Ihre OAuth-Anmeldeinformationen für einen funktionierenden SSE/HTTP + OAuth MCP-Server mit Ihrer eigenen Funktionalität einbinden.

Aber warum?

Gute Frage! Die MCP-Spezifikation wurde am 25. März 2025 um die OAuth-basierte Autorisierungsspezifikation erweitert. Stand 1. Mai 2025:

• Das Typescript SDK enthält viele Bausteine für die Erstellung eines OAuth-autorisierten MCP-Servers mit streambarem HTTP, es gibt jedoch keine Dokumentation oder Anleitung zum Erstellen eines solchen Servers.
• Das Python SDK enthält weder eine Implementierung des streambaren HTTP-Transports noch eine Implementierung der OAuth-Bausteine, die im Typescript SDK vorhanden sind.
• Der Streamable-HTTP-Transport wird von MCP-Hostanwendungen wie Cursor und Claude Desktop weitgehend nicht unterstützt, kann jedoch mithilfe der StreamableHttpClientTransport -Klasse des JS/TS SDK direkt in in JavaScript geschriebene Agenten integriert werden.

Bei Naptha AI wollten wir unbedingt einen OAuth-autorisierten MCP-Server auf dem streambaren HTTP-Transport erstellen und konnten keine Referenzimplementierungen finden. Deshalb haben wir beschlossen, selbst einen zu erstellen!

Abhängigkeiten

Bun , eine schnelle All-in-One-JavaScript-Runtime, ist die empfohlene Runtime und der empfohlene Paketmanager für dieses Repository. Es wurden eingeschränkte Kompatibilitätstests mit npm + tsc durchgeführt.

Überblick

Dieses Repository bietet Folgendes:

1. Ein MCP-Server, den Sie problemlos durch Ihren eigenen ersetzen können
2. Eine Express.js-Anwendung, die sowohl die SSE- und Streamable-HTTP-Transporte als auch die OAuth-Autorisierung verwaltet.

In diese Expressanwendung stecken Sie Ihre Anmeldeinformationen und Ihren MCP-Server.

Beachten Sie, dass diese Express-App zwar die erforderlichen OAuth-Endpunkte einschließlich /authorize und den Endpunkt „Authorization Server Metadata“ ( RFC8414 ) implementiert, jedoch keinen OAuth-Autorisierungsserver!

Dieses Beispiel leitet OAuth an einen Upstream-OAuth-Server weiter, der dynamische Client-Registrierung unterstützt ( RFC7591 ). Für dieses Beispiel benötigen Sie einen eigenen Autorisierungsserver. Wir empfehlen die Verwendung von Auth0 ; siehe Abschnitt „OAuth einrichten“ weiter unten.

Konfigurieren Ihres Servers

Hinweise zu OAuth und dynamischer Client-Registrierung

Für dieses Beispiel benötigen Sie einen OAuth-Autorisierungsserver. Implementieren Sie diesen nicht selbst! Für unsere Demo haben wir Auth0 verwendet – eine hervorragende Option, obwohl es viele andere gibt.

Die MCP-Spezifikation erfordert Unterstützung für eine ungewöhnliche OAuth-Funktion, insbesondere RFC7591 , die dynamische Client-Registrierung. Die MCP-Spezifikation legt fest, dass MCP-Clients und -Server das Protokoll der dynamischen Client-Registrierung unterstützen müssen, damit MCP-Clients (unabhängig vom Standort Ihres Client-Transports) Client-IDs ohne Benutzerregistrierung erhalten können. Dadurch können sich neue Clients (Agenten, Apps usw.) automatisch bei neuen Servern registrieren. Weitere Details hierzu finden Sie im Autorisierungsabschnitt der MCP-Spezifikation . Dies bedeutet jedoch leider, dass Sie nicht einfach direkt zu Anbietern wie Google oder GitHub provisorisch kommunizieren können, da diese keine dynamische Client-Registrierung unterstützen (Sie müssen Ihre Clients in ihrer Benutzeroberfläche registrieren).

Sie haben dann zwei Möglichkeiten:

1. Wählen Sie einen Upstream-OAuth-Anbieter wie Auth0, der Ihnen die Verwendung von OIDC-IDPs wie Google und GitHub zur Authentifizierung ermöglicht und der die dynamische Client-Registrierung unterstützt , oder
2. Implementieren Sie die dynamische Client-Registrierung selbst in der Anwendung (d. h. die Express-Anwendung wird nicht nur zu einem einfachen OAuth-Proxy, sondern zu einem vollständigen oder teilweisen OAuth-Server). Cloudflare hat eine ähnliche Implementierung für seine Workers OAuth MCP-Server implementiert, um die wir dieses Projekt später möglicherweise erweitern werden. Sie finden sie hier .

Der Einfachheit halber haben wir uns für die erste Option mit Auth0 entschieden.

[!NOTIZ]
Da diese Implementierung den Upstream-OAuth-Server als Proxy nutzt, würde der Standardansatz, das Zugriffstoken vom OAuth-Server an den Client weiterzuleiten, das Upstream-Zugriffstoken des Benutzers dem Downstream-Client und MCP-Host zugänglich machen. Dies ist für viele Anwendungsfälle nicht geeignet. Daher werden bei diesem Ansatz einige @modelcontextprotocol/typescript-sdk -Klassen neu implementiert, um dieses Problem zu beheben.

Beachten Sie, dass wir beim Proxying des Upstream-Autorisierungsservers das Authentifizierungstoken des Endbenutzers nicht an den MCP-Client/Host zurückgeben. Stattdessen stellen wir unser eigenes Token aus und ermöglichen dem Client/Host, dieses Token zur Autorisierung bei unserem Server zu verwenden. Dies verhindert, dass ein böswilliger Client oder Host das Token missbraucht oder dass es missbraucht wird, wenn es durchgesickert ist.

Einrichten von OAuth mit Auth0

So beginnen Sie mit Auth0:

1. Erstellen Sie ein Auth0-Konto bei Auth0.com .
2. Erstellen Sie mindestens eine Verbindung zu einem IDP wie Google oder GitHub. Wie das geht, erfahren Sie hier .
3. Erweitern Sie die Verbindung auf Domänenebene . Da neue OAuth-Clients von jedem MCP-Client registriert werden, können Sie Ihre IDP-Verbindungen nicht pro Anwendung/Client konfigurieren. Das bedeutet, dass Ihre Verbindungen für alle Apps in Ihrer Domäne verfügbar sein müssen. Wie das geht, erfahren Sie hier .
4. Aktivieren Sie die dynamische Client-Registrierung (auth0 nennt dies auch „Dynamische Anwendungsregistrierung“). Wie das geht, erfahren Sie hier .

Sobald alles eingerichtet ist, benötigen Sie die folgenden Informationen:

• Ihre Auth0-Client-ID
• Ihr Auth0-Client-Geheimnis
• Ihre Auth0-Mandantendomäne

Stellen Sie sicher, dass Sie diese Informationen in Ihre .env eintragen. Kopieren Sie .env.template und aktualisieren Sie die Werte anschließend mit Ihren Konfigurationen und Geheimnissen.

Ausführen des Servers

Dieses Repository umfasst zwei separate eigenständige Server:

• Eine zustandslose Implementierung des streambaren HTTP-Servers unter src/app.stateless.ts . Diese unterstützt ausschließlich den streambaren HTTP-Transport und ist (theoretisch) für die serverlose Bereitstellung geeignet.
• Eine zustandsbehaftete Implementierung von SSE und streambarem HTTP unter src/app.stateful.ts . Diese App bietet beide Transportmöglichkeiten, behält aber auch bei Verwendung der redis -Speicherstrategie den In-Memory-Status bei (Verbindungen müssen im Speicher gespeichert bleiben). Daher ist sie nicht für serverlose Bereitstellungen oder einfache horizontale Skalierung geeignet.

Sie können beide mit bun ausführen:

Alles zusammenfügen

Um unseren MCP-Server mit streambarem HTTP und OAuth-Unterstützung zu testen, haben Sie mehrere Möglichkeiten.

Wie oben erwähnt, unterstützt das Python MCP SDK diese Funktionen nicht. Daher können Sie unseren Remote-Server derzeit entweder an einen MCP-Host wie Cursor oder Claude Desktop oder direkt an eine TypeScript-/JavaScript-Anwendung anschließen – jedoch nicht an eine Python-Anwendung.

Schließen Sie Ihren Server an Ihren MCP-Host an (Cursor / Claude)

Da die meisten MCP-Hosts weder streambares HTTP (das SSE in vielerlei Hinsicht überlegen ist) noch OAuth unterstützen, empfehlen wir die Verwendung des mcp-remote npm-Pakets, das die OAuth-Autorisierung übernimmt und den Remote-Transport in einen STDIO-Transport für Ihren Host überbrückt.

der Befehl sieht folgendermaßen aus:

Für die Option --transport stehen Ihnen mehrere Optionen zur Verfügung:

• http-first (Standard): Versucht zuerst den HTTP-Transport und greift auf SSE zurück, wenn HTTP mit einem 404-Fehler fehlschlägt
• sse-first : Versucht zuerst den SSE-Transport und greift auf HTTP zurück, wenn SSE mit einem 405-Fehler fehlschlägt
• http-only : Verwendet nur HTTP-Transport, schlägt fehl, wenn der Server dies nicht unterstützt
• sse-only : Verwendet nur SSE-Transport, schlägt fehl, wenn der Server es nicht unterstützt

[!NOTE] Wenn Sie die zustandslose Version des Servers mit src/app.stateless.ts starten, ist der SSE-Transport nicht verfügbar. Verwenden Sie daher --transport http-only . Bei Verwendung dieses Einstiegspunkts ist nicht davon auszugehen, dass der SSE-Transport funktioniert.

Schließen Sie Ihren Server an Ihren Agenten an

Sie können Ihren Streamable-HTTP-Server mithilfe von StreamableHTTPClientTransport an einen Agenten in JS/TS anschließen. Dies funktioniert jedoch nicht mit OAuth-geschützten Servern. Verwenden Sie stattdessen den Authorization auf der Clientseite und ein gültiges Zugriffstoken auf der Serverseite.

Sie können dies mit Client-Anmeldeinformationen, API-Schlüsseln oder anderen Methoden implementieren. Dieses Muster wird in diesem Repository nicht unterstützt, würde aber mit dem Vercel AI SDK folgendermaßen aussehen: