conduit-mcp

Remote-MCP-Server, der mehrere SaaS-Integrationen hinter drei Meta-Tools bereitstellt. Anstatt jedem Client über hundert Tools zur Verfügung zu stellen, stellt der Server list_integrations, find_tools und invoke_tool bereit: Clients durchsuchen den Katalog nach Aufgabenbeschreibung, erhalten passende Toolschemata und rufen diese per exaktem Namen auf. Ein Admin-Portal verwaltet Plugins, API-Schlüssel, Rollen und Nutzung.

Gebündelte Integrationen: HaloPSA, Hudu, CIPP, NinjaRMM, QuickBooks Online.

Layout

Related MCP server: production-grade-mcp-agentic-system

So führen Sie es aus

Erfordert Node >= 22 und pnpm über Corepack (Version festgelegt in package.json packageManager).

corepack enable
scripts/setup.ps1    # or setup.sh: frozen-lockfile install + full workspace build
pnpm dev

pnpm dev führt alles in einem Terminal über concurrently aus, die Ausgabe ist pro Prozess mit Präfix versehen: Azurite (In-Memory-Tabellenspeicher), SDK- und Server-tsc-Watcher, der API-Server und Next Dev. Strg+C beendet alles. pnpm serve überspringt die Watcher und stellt nur die vorgebaute API + das statische Webexport bereit.

• Portal: http://localhost:3000 (Next Dev, leitet API-Aufrufe an :4000 weiter)

• API + MCP: http://localhost:4000 (/healthz, /mcp)

Ohne Konfiguration startet der Server unkonfiguriert und das Portal zeigt den Bootstrap-Setup-Assistenten, der durch die Entra-App-Einrichtung führt. Um ihn zu überspringen, kopieren Sie .dev.env.example nach .dev.env und seeden Sie vorab ENTRA_TENANT_ID / ENTRA_CLIENT_ID / BOOTSTRAP_ADMIN_OID; pnpm dev lädt sie beim Start.

Repository-weite Prüfungen: pnpm lint, pnpm typecheck, pnpm test, pnpm build.

So funktioniert es

MCP-Oberfläche. /mcp spricht streambares HTTP. Anfragen authentifizieren sich mit einem Entra-Bearer-Token oder einem Conduit-API-Schlüssel. Für Clients, die nur OAuth sprechen, leitet der Server die Autorisierung an Entra weiter (Autorisierungsserver-Metadaten + dynamische Client-Registrierung). Sitzungen und Ereignisstreams werden im Tabellenspeicher persistiert, sodass Streams Wiederverbindungen überstehen.

Katalog + Meta-Tools. Jedes Plugin-Tool wird in einen durchsuchbaren Katalog (minisearch) indiziert. find_tools liefert passende Toolschemata zurück, invoke_tool führt per exaktem Namen aus und zeichnet die Nutzung auf. Berechtigungen filtern sowohl Suchtreffer als auch Aufrufe, sodass ein Prinzipal nur die Tools sieht, die seine Berechtigungen erlauben.

Plugins. Ein Plugin ist ein Quellverzeichnis mit einem conduit.plugin.json-Manifest (ID, Einstiegspunkt, Secret-Namen, Portal-Settings-UI, öffentliche Routen). Der Loader bündelt den Einstiegspunkt mit esbuild zur Ladezeit gegen das SDK des Hosts, registriert seine Tools im Katalog und mountet alle Portal-Routen unter /api/plugins/:pluginId. Die Pakete in packages/plugins werden automatisch angesiedelt; weitere können über das Portal aus Git installiert werden. docs/writing-plugins.md behandelt das Erstellen eines Plugins gegen das SDK und das Installieren eines benutzerdefinierten.

Authentifizierungsmodell. Prinzipal sind Entra-Benutzer oder API-Schlüssel. Rollen tragen pro Integration Berechtigungen (schreibgeschützt oder voll, bis hin zu einzelnen Tools) und werden pro Anfrage aufgelöst; Portalzugriff ist eine separate Oberfläche, Portalrollen erweitern niemals den MCP-Toolzugriff. BOOTSTRAP_ADMIN_OID seedet den ersten Administrator.

Speicher + Geheimnisse. Azure Table Storage hält den gesamten Zustand (Konfiguration, Plugin-Registry, Rollen, API-Schlüssel, Nutzung, MCP-Sitzungen); Azurite steht lokal als Ersatz. Geheimnisse gehen in den Key Vault, wenn AZURE_KEYVAULT_URL gesetzt ist, andernfalls als einfache Umgebungsvariablen.

Portal. Next.js-Static-Export, der in Produktion vom API-Server selbst bereitgestellt wird (apps/web/out); im lokalen Watch-Modus läuft stattdessen next dev.

Bereitstellung

Dockerfile baut ein eigenständiges Server-Image mit eingebettetem Web-Export. CI (.github/workflows/deploy.yml) testet, baut und pusht bei jedem Push auf main ghcr.io/<owner>/<repo>:<sha>. Nur bei der ersten Veröffentlichung: Das Paket ist standardmäßig privat; stellen Sie es in den Repository-Einstellungen > Pakete auf öffentlich um, damit App Service ohne Registry-Anmeldeinformationen ziehen kann.

infra/main.bicep (Abonnementbereich) stellt die Ressourcengruppe, App Service, Speicher und Key Vault bereit. Die Entra-App-Registrierung erfolgt auf eine von zwei Arten:

Setup-Assistent, ein Bicep-Lauf. Stellen Sie mit leeren Entra-Parametern bereit und öffnen Sie das Portal: Der Bootstrap-Assistent meldet Sie per Gerätecode an, erstellt die App-Registrierung über Graph und schreibt Mandanten-/Client-IDs in den Konfigurationsspeicher. /api/setup/* ist bis zum Abschluss des Setups unauthentifiziert und der erste Anmelder wird Admin (Trust-on-First-Use); das Setup-Gate gibt danach für diese Endpunkte 404 zurück.

Skriptbasiert, zwei Bicep-Läufe. Kein offenes Setup-Fenster, der Server startet bereits konfiguriert. Das Entra-Skript benötigt die Ausgaben von Lauf 1 (WebApp-URL für Redirect-URIs, Key-Vault-Name für das Client-Secret), und Bicep kann selbst keine App-Registrierungen erstellen, daher der zweite Lauf, um die IDs als App-Einstellungen zu hinterlegen.

# 1. infra, entra params blank. operatorObjectId grants the KV write step 2 needs
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid>

# 2. app registration + client secret into key vault
#    PS7, az login as a user with Application.ReadWrite.OwnedBy, -DryRun to preview
./infra/scripts/setup-entra-app.ps1 -DisplayName "conduit-mcp" \
  -ProdUrl <webAppUrl output> -KeyVaultName <keyVaultName output>

# 3. same deployment plus the ids the script printed
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid> \
     entraTenantId=<tenant-id> entraClientId=<client-id>

Die Änderung der App-Einstellungen startet den Container neu; beim Boot werden die IDs in den Konfigurationsspeicher eingepflegt (füllt nur leere Felder, die Config-Put bleibt maßgeblich).

Continuous Deploy, opt-in. Erstellen Sie eine OIDC-Föderation für den Workflow, setzen Sie die Secrets AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID und die Variablen AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP, setzen Sie dann die Repo-Variable AZURE_DEPLOY=true. Pushes auf main richten die WebApp anschließend auf das frisch gepushte Image aus.

Updates im Portal. Die Einstellungen zeigen, ob das Registry-Image vom laufenden Build abweicht (CI bäckt den Git-SHA in das Image) und können die App neu starten, um es zu ziehen; der Neustart verwendet eine nur für Neustarts vorgesehene benutzerdefinierte Rolle, die dem Managed Identity von Bicep gewährt wird. Bereitstellungen, die vor Existenz dieser Rolle erstellt wurden, benötigen einen erneuten Bicep-Lauf, damit die Schaltfläche funktioniert.