MCP-Server-Vorlage mit Descope-Authentifizierung

Eine einfache FastMCP-Server-Vorlage für Render mit vollständiger MCP-Authentifizierung durch Descope.

Was ist enthalten

• Ein funktionierender MCP-Server unter Verwendung von FastMCP mit Streamable HTTP-Transport

• Vollständige Unterstützung für MCP-Autorisierung mit FastMCPs DescopeProvider und dem descope-mcp SDK

• Ein Beispiel-Tool (hello), das "Hello, world!" zurückgibt und bereichsbasierte Anforderungen auf Tool-Ebene (mcp:greet) durchsetzt

• Ein render.yaml Blueprint für eine einfache Bereitstellung

Hinweis: Diese Vorlage wird standardmäßig im kostenlosen Tarif von Render bereitgestellt. Kostenlose Dienste werden nach 15 Minuten Inaktivität heruntergefahren, was bei der nächsten Anfrage zu Kaltstarts von 30-60 Sekunden führt. MCP-Clients könnten während dieser Verzögerung eine Zeitüberschreitung (Timeout) erleiden. Für eine zuverlässige Nutzung führen Sie ein Upgrade auf einen kostenpflichtigen Tarif im Render-Dashboard durch – der Starter-Tarif hält Ihren Dienst kontinuierlich am Laufen.

Related MCP server: MCP Server Template

Voraussetzungen

• Python 3.13+

• uv

• Ein Descope-Konto und -Projekt

Descope-Einrichtung

1. Melden Sie sich in der Descope Console an.

2. Navigieren Sie zu Agentic Identity Hub → MCP Servers.

3. Klicken Sie auf + MCP Server, um einen neuen MCP-Server zu erstellen und ihm einen Namen zu geben.

4. Aktivieren Sie unter MCP Client Registration die Optionen Client ID Metadata Documents (CIMD) und Dynamic Client Registration (DCR). Optional können Sie erlaubte Domains für Clients einschränken, die sich über CIMD registrieren (z. B. https://claude.ai) – Sie können dieses Feld auch leer lassen.

5. Fügen Sie unter MCP Server Scopes einen Bereich namens mcp:greet mit einer einfachen Beschreibung wie "Begrüße den Benutzer" hinzu.

6. Klicken Sie auf Create.

7. Erweitern Sie den Abschnitt Connect your MCP server to Descope auf der Bestätigungsseite.

8. Kopieren Sie die Well-Known URL. Sie sieht so aus:

   https://api.descope.com/v1/apps/agentic/.../.well-known/openid-configuration

   Dies ist Ihre DESCOPE_CONFIG_URL.

Hinweis: Descope stellt Token gemäß Resource Indicators (RFC 8707) aus, wie von der MCP-Spezifikation gefordert. Wenn Sie auf Render bereitstellen oder lokal ausführen, müssen Sie den Abschnitt für MCP-Server-URLs aktualisieren.

Bereitstellung auf Render

Stellen Sie sicher, dass Sie den Schritt Descope-Einrichtung vor der lokalen Entwicklung abgeschlossen haben, da Sie Ihre DESCOPE_CONFIG_URL benötigen.

1. Forken Sie dieses Repository in Ihr GitHub-Konto.

2. Klicken Sie auf Deploy to Render (oder forken Sie dieses Repo auf GitHub und importieren Sie es als Blueprint in Ihr Render-Konto).

   

3. Legen Sie in Ihren angegebenen Konfigurationen die Umgebungsvariable auf den Wert fest, den Sie im Schritt Descope-Einrichtung erhalten haben:

   Schlüssel	Wert
   DESCOPE_CONFIG_URL	Ihre Well-Known URL aus der Descope Console

4. Klicken Sie auf Deploy Blueprint.

5. Sobald der Dienst live ist, kopieren Sie Ihre Render-Dienst-URL (z. B. https://<your-project>.onrender.com), hängen /mcp an und fügen Sie sie in der Descope Console unter MCP Server URLs hinzu.

Sie verfügen nun über einen remote gehosteten MCP-Server mit vollständiger Unterstützung der Auth-Spezifikation!

Lokale Entwicklung

Stellen Sie sicher, dass Sie den Schritt Descope-Einrichtung vor der lokalen Entwicklung abgeschlossen haben, da Sie Ihre DESCOPE_CONFIG_URL benötigen.

Forken Sie zuerst dieses Repo in Ihr GitHub-Konto und befolgen Sie dann die unten stehenden Anweisungen, um Ihre Umgebung einzurichten.

# Install dependencies
uv sync

# Set required environment variables
export DESCOPE_CONFIG_URL="<your URL from Descope>"
export SERVER_URL="http://localhost:8000"

# Run the server
uv run server.py --transport http --port 8000

Wenn Sie dies lokal ausführen, läuft Ihr Server unter http://localhost:8000/mcp.

Verfügbare Tools

Nächste Schritte

Nachdem Sie alles eingerichtet haben, empfehlen wir einige weitere Schritte, wenn Sie Ihren MCP-Server in die Produktion überführen möchten.

Eigene Tools hinzufügen

Ersetzen oder erweitern Sie das hello-Tool in server.py mit Ihrer eigenen Logik. Für jedes neue Tool:

1. Definieren Sie einen neuen Bereich in der Descope Console unter MCP Server Scopes (z. B. mcp:your-scope).

2. Fügen Sie das Tool mit dem @mcp.tool()-Dekorator hinzu.

3. Rufen Sie require_scopes(token, ["mcp:your-scope"]) innerhalb des Tool-Bodys auf, um die Zugriffskontrolle durchzusetzen.

4. Fügen Sie das neue Tool und den erforderlichen Bereich zur obigen Tabelle Verfügbare Tools hinzu.

@mcp.tool()
def my_tool() -> str:
    token = validate_token()
    require_scopes(token, ["mcp:your-scope"])
    return "your result"

Eigene Domain auf Render verwenden

Standardmäßig ist Ihr Dienst unter https://<your-project>.onrender.com erreichbar. Um eine eigene Domain zu verwenden:

1. Gehen Sie im Render-Dashboard zu Ihrem Dienst → Settings → Custom Domains.

2. Fügen Sie Ihre Domain hinzu und befolgen Sie die bereitgestellten DNS-Anweisungen.

3. Sobald die Domain verifiziert ist, aktualisieren Sie die MCP Server URLs in der Descope Console, um Ihre eigene Domain zu verwenden (z. B. https://mcp.yourdomain.com/mcp).

4. Es sind keine Codeänderungen erforderlich – RENDER_EXTERNAL_URL wird automatisch von Render gesetzt und spiegelt die primäre Domain wider.

Alle Tools mit Bereichen schützen

Die require_scopes()-Prüfung ist absichtlich pro Tool optional, damit Sie bei Bedarf nicht authentifizierte Tools hinzufügen können. Für einen Produktionsserver ist es bewährte Praxis, require_scopes() in jedem Tool aufzurufen. Sie können dies auch zentralisieren, indem Sie einen Helfer schreiben, der validate_token() und require_scopes() umschließt und diesen am Anfang jedes Tool-Handlers aufruft.

Funktionsweise der MCP-Authentifizierung

1. Ein MCP-Client (z. B. Claude Desktop, Cursor) entdeckt OAuth-Metadaten unter /.well-known/oauth-authorization-server, wenn er versucht, eine Verbindung zu Ihrem MCP-Server herzustellen.

2. Der Client registriert sich dynamisch (über CIMD oder DCR) beim Autorisierungsserver und leitet den Benutzer zum Login-/Zustimmungsfluss von Descope weiter.

3. Nach dem Login stellt Descope ein signiertes JWT aus. Der Client fügt dieses als Bearer-Token in jede MCP-Anfrage ein.

4. DescopeProvider validiert das JWT mithilfe des JWKS-Endpunkts von Descope, bevor ein Tool aufgerufen wird.

5. Innerhalb des Tools analysiert validate_token() die Claims und require_scopes() prüft, ob mcp:greet vorhanden ist, und gibt andernfalls einen Fehler an den Client zurück.

Mehr erfahren

• Render Blueprints

• MCP-Autorisierung

• FastMCP

• Descope Agentic Identity Hub docs

• Descope MCP SDK