Selbst-Hosting des Didit MCP Servers

Wichtige Erkenntnisse

• Der Didit Model Context Protocol (MCP) Server ist Open Source unter der MIT-Lizenz. Sie können ihn aus dem öffentlichen GitHub-Repository erstellen und mit Docker, Node.js oder einem "headless stdio"-Transport ausführen.
• Selbst-Hosting ändert, wo der MCP-Prozess läuft, nicht wie er Didit erreicht. Jeder Modus authentifiziert sich als Didit-Benutzer mit einem Bearer-Zugriffstoken. Es gibt keinen Anwendungs-API-Schlüsselmodus für MCP-Tools.
• Der vollständige selbst gehostete Katalog enthält 121 Tools. Der gehostete Open Authorization (OAuth)-Endpunkt macht absichtlich 115 verfügbar. Beispiele in der aktuellen Quelle sind didit_context_get, didit_session_create und didit_transaction_screen_wallet.
• Der HTTP-Einstiegspunkt ist zustandslos und akzeptiert MCP-Verkehr über POST-Anfragen. Pro Anfrage werden ein neuer Server und Transport erstellt, sodass ein Load Balancer keine Session Affinity benötigt.
• Verwenden Sie /healthz für Container- und Load-Balancer-Checks. Konfigurieren Sie die öffentliche Ressourcen-URI, den Autorisierungs-Origin, den Token-Verifizierungsmodus und die Geheimnisse explizit, bevor Sie den Dienst freigeben.

Der gehostete Endpunkt ist praktisch, aber nicht für jedes Team die richtige operative Wahl. Ein Unternehmen muss möglicherweise die Integration innerhalb der eigenen Netzwerkbegrenzung halten, das Laufzeit-Image kontrollieren, den Datenverkehr über eine private Egress-Schicht leiten oder eigene Observability- und Änderungsmanagementrichtlinien anwenden. Das Didit MCP-Repository unterstützt dieses Bereitstellungsmodell, ohne eine separate Produktoberfläche zu schaffen.

Dieser Leitfaden konzentriert sich nur auf den Betrieb des Servers. Für den Katalog und das Tool-Verhalten verwenden Sie die Didit MCP Tools Referenz. Für die Client-Einrichtung am verwalteten Endpunkt verwenden Sie den Claude Installationsleitfaden. Die vollständigen technischen Referenzen finden Sie in der MCP-Übersicht und der Authentifizierungsdokumentation.

Wählen Sie den HTTP- oder stdio-Einstiegspunkt

Das Repository erstellt einen gemeinsamen Tool-Katalog mit zwei Einstiegspunkten. dist/http.js betreibt einen Express-Ressourcenserver über zustandsloses Streamable HTTP. Dies ist die richtige Wahl für einen gemeinsamen Dienst, der von mehreren MCP-Clients, Containern oder Benutzern erreicht wird. dist/index.js läuft über stdio und ist für einen "headless" lokalen Prozess gedacht, der von einem Client gestartet wird.

Beide Einstiegspunkte rufen dieselbe Dispatch-Logik auf, und Version 5 macht nur MCP-Tools verfügbar – nicht MCP-Ressourcen oder Prompts. Beide authentifizieren Downstream-Anfragen als Didit-Benutzer. Der Unterschied besteht darin, wie diese Benutzeranmeldeinformationen den Prozess erreichen: Der HTTP-Einstiegspunkt empfängt und validiert das OAuth-Bearer-Token des Aufrufers; der stdio-Einstiegspunkt liest ein Benutzer-Bearer-Token aus DIDIT_ACCESS_TOKEN.

Selbst gehostet bedeutet nicht "ohne Anmeldeinformationen": Das MCP fungiert immer noch als Didit-Benutzer, und Didit wendet die Organisationsrolle und Berechtigungen dieses Benutzers auf jeden Tool-Aufruf an.

Erstellen und Ausführen mit Docker

Das Repository enthält eine mehrstufige Dockerfile, die auf Node 20 basiert. Die Build-Phase installiert Entwicklungsabhängigkeiten, kompiliert TypeScript und bereinigt Entwicklungspakete. Die Produktionsphase läuft als nicht-root node-Benutzer und enthält einen Container-Health-Check.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

Bevor Sie den Container starten, ersetzen Sie die gehosteten Standardwerte, die Ihre Bereitstellung identifizieren. Setzen Sie mindestens MCP_RESOURCE_URI auf den öffentlichen Ursprung, über den Clients diesen Ressourcenserver erreichen, und geben Sie dann die OAuth-Client-Anmeldeinformationen an, die für die Token-Introspektion erforderlich sind. Bewahren Sie Geheimnisse im Secret Manager Ihrer Container-Plattform auf, anstatt die ausgefüllte .env-Datei zu committen.

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Beenden Sie Transport Layer Security (TLS) an Ihrem Ingress oder Load Balancer, leiten Sie MCP POST-Anfragen an Port 3000 weiter und bewahren Sie den Authorization-Header auf. Die extern sichtbare MCP_RESOURCE_URI muss mit der Ressourcenidentität übereinstimmen, die Clients angekündigt wird; lassen Sie die verwaltete Didit-URI nicht für einen anderen öffentlichen Ursprung an Ort und Stelle.

Direkt mit Node.js erstellen und ausführen

Wenn Ihre Plattform bereits eine Node-Laufzeit verwaltet, verwenden Sie denselben HTTP-Einstiegspunkt ohne Container. Das Paket ist privat und wird nicht über npm verteilt, daher klonen Sie das Repository, anstatt zu versuchen, ein veröffentlichtes Paket auszuführen.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

Der Prozess liest dieselben Umgebungsvariablen wie der Container. Führen Sie ihn unter Ihrem Prozess-Supervisor aus, injizieren Sie Geheimnisse über die Bereitstellungsumgebung und leiten Sie nur die erforderlichen Endpunkte weiter. MCP-Anfragen gehen an POST /mcp. Der Dienst lehnt GET und DELETE auf dieser Route absichtlich ab, da er keine MCP-Sitzungen oder vom Server initiierte Streams verwaltet.

Node.js lädt die .env-Datei des Repositorys nicht automatisch. Exportieren Sie die Werte in der Shell, injizieren Sie sie über den Dienstmanager oder verwenden Sie die Unterstützung für Umgebungsdateien Ihrer Plattform, bevor Sie dist/http.js starten. Beachten Sie auch, dass npm start den stdio-Einstiegspunkt startet; verwenden Sie node dist/http.js oder npm run start:http für HTTP.

Headless über stdio ausführen

Für einen lokalen Agenten, Build-Runner oder isolierten Einzelclient-Prozess verwenden Sie den stdio-Einstiegspunkt. Stellen Sie ein Benutzerzugriffstoken über die Umgebung bereit und lassen Sie den MCP-Client den Lebenszyklus des Prozesses steuern.

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

Dieses Token ist eine Benutzer-Bearer-Anmeldeinformation, keine Anwendungs-Anmeldeinformation. Speichern Sie es als Geheimnis, halten Sie es aus der Shell-Historie und den Protokollen fern und rotieren Sie es gemäß Ihrer Zugriffsrichtlinie. Wenn eine Bereitstellung immer in einer Organisation oder Anwendung betrieben wird, können MCP_DEFAULT_ORG und MCP_DEFAULT_APP diesen Standardbereich bereitstellen. Andernfalls können Tools den Bereich aus expliziten Argumenten oder dem authentifizierten Anfragekontext auflösen.

Es gibt immer noch keinen Anwendungs-API-Schlüsselmodus in stdio. Selbst gehostetes HTTP und selbst gehostetes stdio rufen beide benutzerbezogene Didit-Konsolenendpunkte auf, sodass ein Anwendungsschlüssel das Benutzer-Bearer-Token nicht ersetzen kann.

Konfigurieren Sie die vollständige Umgebungsoberfläche

Die aktuelle src/config.ts unterstützt die folgenden Variablen. Die meisten Bereitstellungen sollten die Produktions-Didit-API und Autorisierungsstandards beibehalten und nur die Ressourcenidentität, die Verifizierungskonfiguration und die Geheimnisse überschreiben, die für ihre Topologie erforderlich sind.

Gemeinsame und stdio-Variablen

• DIDIT_ACCESS_TOKEN: Benutzer-Bearer-Token für den Headless-stdio-Modus; kein Standardwert.
• DIDIT_API_BASE_URL: Basis-URL der Verifizierungs-API; Standardwert ist https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: Basis-URL der Authentifizierungs-API; Standardwert ist https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG und MCP_DEFAULT_APP: Optionale Organisations- und Anwendungsstandardwerte für Single-Tenant-Bereitstellungen.

HTTP-Ressourcenserver-Variablen

• MCP_PORT: Listen-Port; Standardwert ist 3000.
• MCP_RESOURCE_URI: Öffentliche Ressourcen-Server-URI; Standardwert ist https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: Autorisierungs-Server-Origin; Standardwert ist https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: Standardmäßig introspection oder jwks, wenn der Autorisierungsdienst JSON Web Tokens (JWTs) ausstellt, die für die lokale Signaturverifizierung geeignet sind.
• MCP_OAUTH_CLIENT_ID und MCP_OAUTH_CLIENT_SECRET: Keine Standardwerte; werden als HTTP Basic-Anmeldeinformationen für die Request for Comments (RFC) 7662 Introspektion verwendet.
• MCP_OAUTH_INTROSPECT_URL: Standardwert ist https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: Leerzeichengetrennte Discovery-Scopes; Standardwert ist didit:management didit:verification.

Metadatenüberschreibungen der Autorisierung

• DIDIT_AUTH_ISSUER: Standardwert ist MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: OpenID Connect (OIDC) Discovery-Dokument; Standardwert ist der Autorisierungs-Origin plus /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: JSON Web Key Set (JWKS)-Endpunkt; Standardwert ist https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: Standardwert ist der Autorisierungs-Origin plus /authorize.
• DIDIT_OIDC_TOKEN_URL: Standardwert ist der Autorisierungs-Origin plus /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: Standardwert ist der Autorisierungs-Origin plus /api/auth/oauth-register.

Verwenden Sie introspection für opake Zugriffstoken. Der Server sendet diese an den konfigurierten Introspektions-Endpunkt unter Verwendung von MCP_OAUTH_CLIENT_ID und MCP_OAUTH_CLIENT_SECRET. Verwenden Sie jwks nur, wenn Ihr Autorisierungsdienst so konfiguriert ist, dass er signierte JWT-Zugriffstoken für diesen Client ausstellt; der Server validiert dann Signaturen anhand von DIDIT_JWKS_URL. Das Ändern des Verifizierungsmodus erzeugt kein anderes Identitätsmodell: Der validierte Prinzipal bleibt ein Didit-Benutzer.

MCP-Clients können Dynamic Client Registration (DCR) mit der Didit Business Console während ihres Autorisierungsflusses verwenden. Diese Client-Registrierung ist getrennt von den MCP_OAUTH_CLIENT_ID und MCP_OAUTH_CLIENT_SECRET des Ressourcenservers, die Introspektionsanfragen authentifizieren. Stellen Sie diese serverseitigen Anmeldeinformationen über den entsprechenden Didit-Bereitstellungskanal bereit, anstatt anzunehmen, dass eine Client-Registrierung sie ersetzen kann.

Health Checks und zustandslose Skalierung

Der HTTP-Prozess macht GET /healthz verfügbar und gibt JSON zurück, das status, service und version enthält. Das Docker-Image überprüft dies bereits alle 30 Sekunden nach einer 15-sekündigen Startphase. Sie können denselben Endpunkt für Kubernetes Readiness, eine Application Load Balancer Zielgruppe oder eine externe Uptime-Sonde verwenden.

curl -fsS http://localhost:3000/healthz

Die MCP-Route ist bewusst zustandslos. Für jede authentifizierte POST-Anfrage erstellt der Prozess einen neuen Server und Streamable HTTP-Transport mit deaktivierter Sitzungsgenerierung, leitet die validierten Anmeldeinformationen des Aufrufers über den anfragebezogenen Kontext weiter, schließt den Dispatch ab und beendet den Transport. Es gibt keine In-Memory-Sitzung, die eine spätere Anfrage auf derselben Replika finden müsste.

Hier beschreibt "zustandslos" den MCP-Transport und den Lebenszyklus der Anfrage. Verifizierungssitzungen, Workflows, Fälle und andere Geschäftsaufzeichnungen bleiben in den Upstream-Diensten von Didit bestehen.

Daher benötigen horizontale Replikas keine "sticky sessions". Jede gesunde Instanz kann die nächste POST-Anfrage bearbeiten, und Rolling Deployments erfordern keine Sitzungsentleerung über die normale Bearbeitung laufender Anfragen hinaus. Die Kapazitätsplanung sollte sich auf die Anfragegleichzeitigkeit, die Latenz der Downstream-Didit-API und Ihre normale Timeout- und Wiederholungsrichtlinie konzentrieren.

Validieren Sie, bevor Sie den Dienst freigeben

• Bestätigen Sie, dass /healthz vom selben Netzwerkpfad wie der Load Balancer erfolgreich ist.
• Bestätigen Sie, dass nicht authentifizierte MCP-Anfragen eine Autorisierungsherausforderung erhalten und nicht die Tool-Ausgabe.
• Schließen Sie einen OAuth 2.1-Flow mit Proof Key for Code Exchange (PKCE) ab und rufen Sie dann didit_context_get auf, um zu überprüfen, ob die erwarteten Organisationen und Anwendungen sichtbar sind.
• Lesen Sie die erweiterte MCP-Dokumentation, bevor Sie Discovery-Endpunkte oder die Token-Verifizierung ändern.
• Verwenden Sie die Didit MCP-Entwicklerseite für die unterstützte verwaltete Oberfläche und aktuelle Links.

Wenn Selbst-Hosting keine Anforderung mehr ist, entfernt der verwaltete Endpunkt die oben beschriebenen Laufzeit- und OAuth-Ressourcenserver-Operationen. Claude-Benutzer können ihn mit dem Didit-Konnektor-Deep-Link hinzufügen. Ob Sie den Prozess selbst ausführen oder Didit dies tut, die Kernregel ist identisch: MCP-Operationen authentifizieren sich als Didit-Benutzer, niemals als Anwendungs-API-Schlüssel.