NestJS MCP: Offizielles Modul in bestehende Apps integrieren

Zurück

Kevin Riedl

16 min Lesezeit · 4. November 2026
Zuletzt geprüft 4. November 2026

Weiter

Dein NestJS-Backend weiß bereits, wer eine Rechnung lesen darf und welche Vorgänge sie verändern können. Ein KI-Assistent soll diese Funktionen nutzen, ohne dass du die Regeln deiner Anwendung ein zweites Mal implementierst.

Für die MCP-Anbindung einer bestehenden NestJS-App prüfst du zuerst die Kompatibilität, registrierst McpModule und gibst ausgewählte Provider-Methoden frei. Zugriffsrechte auf einzelne Datensätze und Geschäftslogik bleiben in deinen Anwendungsservices. Prüfe Schemas, Guards und Ergebnisse über einen MCP-Client. Teste anschließend den HTTP-Endpunkt, bevor du einen entfernten Assistenten verbindest.

Geprüft und getestet am 4. November 2026. Wir haben ein Beispiel zur Abfrage des Rechnungsstatus mit @nestjs/mcp 0.0.2 kompiliert und zehn Verhaltensprüfungen ausgeführt, zwei davon über echtes HTTP. Das Testprojekt zum Download verwendet synthetische Daten und Test-Tokens.

Was bringt das offizielle NestJS-MCP-Modul?

NestJS MCP stellt ausgewählte Provider-Methoden als Tools, Ressourcen und Prompts bereit. Das offizielle Modul übernimmt das Protokoll und bindet die Methoden in Dependency Injection und Ausführungspipeline von Nest ein. Du entscheidest, welche Funktionen freigegeben werden. Andere Service-Methoden bleiben außerhalb der MCP-Schnittstelle.

Die README der Release-Version dokumentiert Streamable HTTP mit Express, Fastify und dem Node-Adapter sowie stdio für lokal gestartete Prozesse. Die offizielle Integration heißt @nestjs/mcp; @rekog/mcp-nest ist ein separates Community-Paket. NestJS Observe bietet außerdem einen MCP-Server für seine Observability-Daten.

Ein Support-Assistent kann denselben Rechnungsservice aufrufen wie dein Dashboard. Transaktionsregeln und Mandantenprüfungen bleiben dadurch an einer Stelle. Wir würden mit einem Lesezugriff beginnen. Prüfe, welche Datensätze der Aufrufer sehen darf, welche Felder die Anwendung verlassen und welche Antwort der Assistent bei einem Fehler erhält.

Ist deine bestehende NestJS-App mit dieser Version kompatibel?

@nestjs/mcp 0.0.2 deklariert NestJS 12 und MCP SDK ^2.4.0 als Peer-Dependencies. NestJS 10 und 11 liegen außerhalb dieses Versionsbereichs. Prüfe zuerst deinen Abhängigkeitsbaum. Ein Framework-Upgrade gehört in eine eigene Änderung mit passenden Regressionstests.

Das Paketmanifest von 0.0.2 nennt die folgenden Versionsanforderungen. Unser Testprojekt prüft eine konkret festgelegte Kombination innerhalb dieser Bereiche.

npm ls @nestjs/core @nestjs/common @modelcontextprotocol/server zod

npm install --save-exact @nestjs/[email protected] \
  @modelcontextprotocol/[email protected] [email protected]

npm install --save-dev --save-exact @modelcontextprotocol/[email protected]

Unser Testprojekt kombiniert diese Versionen mit NestJS 12.3.3 und Node.js 24.22.1. Eine ESM-Abhängigkeit verlangt nicht automatisch, deine CommonJS-App umzuschreiben. Prüfe den tatsächlichen Import- und Build-Pfad. Ein Override der Peer-Dependencies weist keine Kompatibilität nach.

Beim Upgrade zählt auch die Schema-Aufbereitung im Quellcode. Zod 3 wird abgelehnt. ArkType wird unterstützt; Valibot benötigt toStandardJsonSchema() aus @valibot/to-json-schema. Vorhandenes JSON Schema lässt sich über fromJsonSchema() aus dem MCP-Serverpaket einbinden. Tool-Argumente brauchen ein Objektschema, das sich entsprechend umwandeln lässt.

Wie integrierst du NestJS MCP in eine bestehende App?

Registriere McpModule und einen Tool-Provider, der den benötigten Anwendungsservice injiziert. Begrenze die automatische Erkennung auf das betreffende Fachmodul. Bevor du sensible Tools über einen geschützten HTTP-Endpunkt erreichbar machst, brauchst du einen echten Token-Verifier.

Die folgende Konfiguration zeigt die Einbindung. InvoicesModule, IdentityModule und IdentityTokenVerifier ergänzt du aus deiner Anwendung.

McpModule.forRoot({
  name: 'billing-assistant',
  version: '1.0.0',
  include: [InvoicesModule],
  imports: [IdentityModule],
  auth: {
    verifier: IdentityTokenVerifier,
    resource: 'https://api.example.com/mcp',
    authorizationServers: ['https://login.example.com'],
  },
})

Importiere außerdem InvoicesModule in die Anwendung und trage InvoiceTools in dessen providers ein. Über die Moduloption imports erhält der Verifier Zugriff auf exportierte Abhängigkeiten. Die Provider-Registry findet dekorierte Methoden beim Start. include legt fest, welche Module sie dafür durchsucht.

Dieser Provider-Ausschnitt stammt aus unserem ausgeführten Testprojekt. Der Download enthält den zugehörigen Service, die Zugriffshilfe, den Guard und das Testmodul.

export const InvoiceInput = z.object({
  invoiceId: z.string().regex(/^inv_[a-z0-9]+$/).max(64),
}).strict();

export const InvoiceStatus = z.object({
  invoiceId: z.string(),
  status: z.enum(['open', 'paid']),
});

@Injectable()
export class InvoiceTools {
  constructor(
    private readonly invoices: InvoicesService,
    private readonly access: InvoiceAccess,
  ) {}

  @Tool({
    name: 'get-invoice-status',
    description: 'Read the status of one invoice available to the signed-in user. Does not modify an invoice.',
    inputSchema: InvoiceInput,
    outputSchema: InvoiceStatus,
    scopes: ['invoices:read'],
    annotations: { readOnlyHint: true },
  })
  @UseGuards(SupportTeamGuard)
  async status(input: z.infer<typeof InvoiceInput>, ctx: McpContext) {
    const actor = this.access.requirePrincipal(ctx);
    return this.invoices.statusForActor(actor, input.invoiceId, ctx.signal);
  }
}

InvoiceAccess liest Benutzeridentität und Mandant aus dem verifizierten Kontext. InvoicesService prüft den Zugriff auf die konkrete Rechnung. Das Modell liefert nur deren Kennung. Ein zusätzlich übergebenes Mandantenfeld kann keine Berechtigung schaffen; das strikte Schema weist nicht deklarierte Felder ab.

Das Beispiel gibt ausschließlich Kennung und Status zurück. Ein ORM-Rechnungsobjekt könnte zusätzlich Adressen, Steuerinformationen oder interne Notizen enthalten. Lege deshalb ausdrücklich fest, welche Felder der Assistent erhalten darf.

Fehlt der Endpunkt, prüfe globales Präfix und Versionierung. Fehlt ein Tool in der Auflistung, prüfe Provider-Registrierung, include und Startfehler. Ein Decorator allein macht eine nicht registrierte Klasse nicht auffindbar.

Welche Methoden werden zu Tools, Ressourcen oder Prompts?

Nutze NestJS-MCP-Tools für parametrisierte Vorgänge, Ressourcen für Daten mit einer URI und Prompts für wiederverwendbare Nachrichtenvorlagen. Jeder dieser Bausteine sollte eine klar umrissene Aufgabe erfüllen. So kannst du Berechtigungen und Fehlerverhalten gemeinsam beurteilen.

Die offizielle Dokumentation der MCP-Bausteine beschreibt Decorators und Rückgabewerte. Für eine Anwendung zur Rechnungsbearbeitung würden wir die Aufgaben so aufteilen:

Ein allgemeines Tool wie run-sql oder call-any-service ist schwerer zu prüfen. Wir bevorzugen eine benannte Geschäftsfunktion mit begrenzten Eingaben. Bei ihr lassen sich erlaubte Datensätze und mögliche Änderungen klarer erkennen.

Funktionieren deine bestehenden Guards bei MCP-Aufrufen?

Bestehende Guards können bei NestJS-MCP-Aufrufen laufen, wenn sie den Ausführungskontext mcp unterstützen. Prüfe dieselbe Annahme bei Interceptors, Pipes und Exception Filters. Wer ausschließlich einen HTTP-Kontext erwartet, kann die falschen Argumente lesen, obwohl der Guard korrekt registriert ist.

Der Helper für den MCP-Ausführungskontext liefert Eingaben, Aufrufkontext und Authentifizierungsinformationen. Unser Guard für dieses Tool liest einen Abteilungs-Claim, den der Verifier des Testprojekts bereitstellt:

@Injectable()
export class SupportTeamGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const ctx = McpExecutionContext.create(context).getContext();
    return ctx.authInfo?.extra?.department === 'support';
  }
}

Wende den Guard auf den MCP-Provider oder dessen Methode an. Ein globaler Guard, den du auch für HTTP-Routen nutzt, muss nach Kontexttyp unterscheiden und in jedem Zweig die passende Policy durchsetzen. Für einen unbekannten Kontext true zurückzugeben, würde diese Prüfung umgehen.

Übergib Benutzer- und Mandantenzustand über Argumente oder den Aufrufkontext. Ein anderer Request kann this.currentTenant auf einem gemeinsam genutzten Provider überschreiben. Die Registry lehnt Abhängigkeitsbäume mit Request-Scope ab. Injiziert ein Provider einen mandantenspezifischen Service mit Request-Scope, musst du diese Konstruktion ändern.

In Version 0.0.2 ist McpContext ein Union-Typ für Client- und interne Agentenkontexte. Prüfe ctx.transport, bevor du reine Client-Felder wie server oder era verwendest. Der optionale idempotencyKey des internen Agenten verhindert wiederholte Schreibzugriffe über entfernte MCP-Clients nicht automatisch.

Interceptors sollten Vorgang, Ergebnis, Korrelationskennung und Laufzeit erfassen. Bearer-Tokens und vollständige Rechnungsinhalte gehören nicht ins Log. Prüfe auch Fehlermeldungen: Eine bewusst geworfene HttpException kann ihren Nachrichtentext an den Aufrufer weitergeben. Formuliere ihn so, dass der Client sinnvoll reagieren kann, ohne interne Datensätze oder Zugangsdaten offenzulegen.

Wie greifen OAuth-Scopes und Benutzerrechte ineinander?

Bei NestJS MCP erlaubt ein OAuth-Scope eine bestimmte Funktion. Die Anwendung entscheidet zusätzlich, auf welche Objekte der Aufrufer zugreifen darf. Das HTTP-Modul prüft Tokens deines Identity Providers. Auch mit einem gültigen Token und dem Scope zum Lesen von Rechnungen brauchst du die Berechtigung für die konkrete Rechnung.

Das Authorization Gate verbindet deinen Verifier mit den OAuth-Challenges. Validiere Aussteller, Signatur beziehungsweise Introspection-Ergebnis, Audience und Ablaufzeit. Ein JWT lediglich zu dekodieren und die konfigurierte Ressourcen-URL zurückzugeben, beweist nicht, dass dieses Token für die Ressource ausgestellt wurde.

Unser Service prüft den Zugriff des Akteurs auf die Rechnung, nachdem der Scope invoices:read die Funktion freigegeben hat. authInfo.clientId identifiziert den OAuth-Client. Benutzeridentität und Mandant musst du gesondert ermitteln. Unsere Architektur für MCP-Autorisierung in Unternehmen behandelt diesen übergreifenden Entwurf.

Für die Integration von @CurrentUser() und @Can() brauchst du konfigurierte Versionen von @nestjs/authentication ab 0.1.3 und @nestjs/authorization ab 0.1.1. Die Integrationstests des Projekts zeigen, wie beide Module Benutzerinformationen und Policies bei Tool-Aufrufen verarbeiten.

Die dokumentierte Einstellung decorators: [Public()] nimmt die Endpunktroute vom Authentication Guard aus. Dadurch kann MCP seine eigene Challenge für die OAuth-Erkennung zurückgeben. Dazu gehören zwingend die MCP-Konfiguration auth und die vorgesehene Autorisierung der Provider. @Public() pauschal auf Tool-Provider anzuwenden, wäre keine gleichwertige Konfiguration.

Bei einem HTTP-Endpunkt führt die Deklaration von Tool-Scopes ohne durchsetzende Auth-Konfiguration zu einem Startfehler. Stdio hat ein eigenes Sicherheitsmodell. Ein OAuth-Scope am Decorator schützt einen lokalen stdio-Aufruf für sich allein nicht.

Was unterscheidet HTTP, stdio und ältere Clients?

NestJS MCP bedient entfernte Clients über Streamable HTTP und lokale Prozesse über stdio. HTTP-Anfragen sind unabhängig voneinander; bei stdio bleibt eine Prozessverbindung bestehen. Gleiche die benötigten Interaktionen deines Clients mit Transport und Protokollgeneration ab. Das ist besonders relevant, wenn ein Tool den Benutzer um weitere Eingaben bittet.

Die Transportdokumentation beschreibt die verfügbaren Möglichkeiten:

Durch zustandsloses HTTP benötigt das Modul keine festen Transport-Sitzungen auf einer bestimmten Instanz. Datenbank, Job-Queue, Rate Limits und fachliche Idempotenz brauchen weiterhin die Konsistenz, die ihre Operationen verlangen. Unser Leitfaden zur Migration auf zustandslose MCP-Server behandelt den Wechsel auf Protokollebene.

Unterscheide bei Browser-Clients zwischen der hostnamebasierten Option allowedOrigins des Moduls und den CORS-Origins von Nest. Anfragen ohne Origin-Header können die Origin-Prüfung passieren. Diese Prüfung ersetzt deshalb keine Authentifizierung. Ein vorgeschalteter HTTP-Body-Parser kann außerdem eine Anfrage ablehnen, bevor das Größenlimit des Moduls greift.

Leite Anwendungslogs bei stdio über McpStdioLogger; stdout transportiert die Protokollnachrichten. Eine erfolgreiche lokale Verbindung prüft weder OAuth-Erkennung noch TLS oder Proxy-Verhalten deines entfernten Deployments.

Was ändert sich bei der Migration von mcp-nest?

Bei der Migration von @rekog/mcp-nest musst du die APIs deiner Community-Paketversion auf die Provider-, Schema- und Kontext-APIs des offiziellen Moduls abbilden. Erfasse zuerst die Funktionen, die du verwendest. Ähnliche Decorator-Namen können unterschiedliches Autorisierungs- oder Transportverhalten verdecken.

Prüfe die folgenden Änderungen anhand des offiziellen Migrationsleitfadens für die 1.x- und 2.x-APIs des Community-Pakets.

Der alte HTTP+SSE-Transport von 2024 und mehrere MCP-Server innerhalb einer Anwendung gehören ebenfalls nicht zum unterstützten Umfang dieser Version. Bei aktivierter HTTP-Authentifizierung lassen sich die anonymen Ausnahmen für einzelne Tools aus dem Community-Modul nicht übernehmen.

Migriere zuerst ein Lese-Tool. Behalte nach Möglichkeit seinen Namen und seinen Schnittstellenvertrag bei. Vergleiche Erkennung, Ergebnisse und abgelehnte Zugriffe mit der bisherigen Integration, bevor du Schreiboperationen und deren Verhalten bei Wiederholungen angehst.

Wie testest du das MCP-Verhalten aus Sicht des Assistenten?

Prüfe das Verhalten von NestJS MCP mit connectMcpClient(). Teste anschließend die HTTP-Route für Middleware und Deployment-Eigenschaften. Direkte Provider-Tests allein überspringen die Protokollpipeline mit Argumentvalidierung, Scope-Prüfung, Guards und Serialisierung der Ergebnisse.

Der Helper für Tests im Speicher ruft den HTTP-Service ohne Socket auf, einschließlich dessen Host- und Origin-Prüfungen. Er überspringt die Middleware des Endpunkts und Routenguards aus decorators. Als Request verwendet er ein vereinfachtes Objekt für http://localhost/mcp.

Dieser Ausschnitt prüft, dass ungültige Eingaben den Rechnungsservice gar nicht erreichen. Das Testprojekt stellt Testmodul und authentifizierten Client bereit und schließt beide anschließend.

const service = moduleRef.get(InvoicesService);
const before = service.calls;

const result = await client.callTool({
  name: 'get-invoice-status',
  arguments: { invoiceId: 123 },
});

assert.equal(result.isError, true);
assert.equal(service.calls, before);

Der Testleitfaden unterscheidet Tool-Fehler von Authentifizierungsfehlern: Ungültige Argumente können isError: true zurückliefern, fehlende Scopes lösen InsufficientScopeError aus, und ohne erforderliches Token scheitert bereits die Verbindung. Wenn du bei jedem Fehler eine abgelehnte Promise erwartest, übersiehst du Fehler in Tool-Ergebnissen.

Wenn du in Produktion allowedHosts setzt, berücksichtige die localhost-URL des Helpers in einer ausschließlich für Tests verwendeten Konfiguration. Behalte die Host-Policy für die Produktion bei.

Was hat unser kleiner Integrationstest nachgewiesen?

Unser NestJS-MCP-Testprojekt bestand acht Prüfungen im Speicher und zwei echte HTTP-Prüfungen mit Express. Es verwendet eine synthetische Rechnung, einen Service-Ersatz mit Mandantenprüfung und feste Test-Tokens. Die Ergebnisse zeigen, wie dieses Beispiel erlaubte und abgelehnte Aufrufe unter diesen Bedingungen behandelt.

Getestet wurden @nestjs/mcp 0.0.2, NestJS 12.3.3, MCP-Client und -Server 2.4.0, Zod 4.6.7, TypeScript 7.0.2 und Node.js 24.22.1. Quellcode, Lockfile der Abhängigkeiten und aufgezeichnete Ausgabe findest du im NestJS-MCP-Testprojekt zum Download.

Um die Prüfungen zu wiederholen, entpacke das Testprojekt und führe in dessen Verzeichnis diese Befehle aus:

npm ci
npm test

Node meldet 12 bestandene Tests, weil es zwei übergeordnete Tests zusätzlich zu den zehn Prüfungen zählt. Der simulierte Verifier gehört ausschließlich in den Testcode. Dieses Beispiel prüft weder Fastify noch den Node-Adapter, produktive Identity Provider, gleichzeitige Schreibzugriffe oder das Verhalten hinter einem Load Balancer.

Was brauchst du vor der Freigabe von Tools mit Schreibzugriff?

Bevor du ein NestJS-MCP-Tool mit Schreibzugriff freigibst, definiere Autorisierung, dauerhafte Vorgangskennung, Regeln für gleichzeitige Zugriffe und Fehlerbehandlung. Der Anwendungsservice muss entscheiden, was bei einer Wiederholung nach einem Timeout passiert. Ein Decorator kann nicht entscheiden, ob eine Zahlung erneut ausgeführt werden darf.

Halte bei einer Rechnungskorrektur die freigegebene Aktion und ihre Eingaben fest. Prüfe den Zugriff bei der Ausführung erneut und behalte dieselbe Vorgangskennung über Wiederholungen hinweg bei. Lehne geänderte Argumente unter derselben Kennung ab. Wurde der erste Versuch bereits gespeichert, aber die Antwort ging verloren, liefere das festgehaltene Ergebnis zurück oder gleiche den tatsächlichen Ausgang ab.

Das ist ein Entwurfsvorschlag und vom ausgeführten Testprojekt mit Lesezugriff zu unterscheiden. Dafür brauchst du Transaktions- und Nebenläufigkeitstests mit deinem tatsächlichen Datenspeicher. Erfindet das Modell bei jedem Versuch einen neuen Idempotency Key, umgeht es eine darauf basierende Duplikatprüfung.

Die MCP-Maintainer beschreiben Tool-Annotationen als Hinweise. readOnlyHint und idempotentHint informieren Clients über das beabsichtigte Verhalten. Die Hinweise setzen es nicht durch. Ebenso wenig begründet ein Prompt, der eine Bestätigung verlangt, die Berechtigung zur Ausführung.

Vor dem ersten Rollout mit Schreibzugriff würden wir diese beobachtbaren Ergebnisse verlangen:

• Ein unberechtigter Akteur oder ein nicht erlaubtes Zielobjekt wird vor jeder dauerhaften Änderung abgewiesen.
• Zwei gleichzeitige Versuche derselben freigegebenen Aktion bewirken genau die beabsichtigte einmalige Änderung.
• Geänderte Eingaben unter derselben Vorgangskennung werden abgelehnt.
• Tritt nach dem Commit ein Timeout auf, lässt sich das Ergebnis abgleichen, ohne die Änderung blind zu wiederholen.
• Ein Audit-Eintrag nennt Akteur, Vorgang, Autorisierungsentscheidung und resultierenden Zustand, ohne Tokens zu speichern.

Setze dieselben Datenzugriffsrechte durch, unabhängig davon, ob die Operation über REST, einen Queue-Job oder MCP erreicht wird. Unser Leitfaden zur Durchsetzung von Datenzugriffsrechten für Agenten erläutert diese Grenze genauer.

Wann würden wir das offizielle NestJS-MCP-Modul einsetzen?

Wir würden das offizielle NestJS-MCP-Modul einsetzen, wenn die Anwendung seine Versionsanforderungen erfüllt und fachliche Berechtigungen bereits in Services durchsetzt. Beginne mit einem Provider-Adapter, dessen Rechte, Ausgabe und Fehlerpfade du nachvollziehen kannst. Prüfe sie über das Protokoll des Clients.

Bei einem Produkt auf NestJS 10 oder 11 musst du zuerst über das Framework-Upgrade entscheiden, bevor du eine MCP-Installation zusagst. Ist dein System auf Provider mit Request-Scope, Tool-Registrierung zur Laufzeit oder mehrere getrennte MCP-Server in einem Prozess angewiesen, kläre diese Abweichung vor dem Austausch einer funktionierenden Integration.

Wavects NestJS-Entwicklung umfasst die dafür nötigen Änderungen an deiner Anwendung. Mit unserer MCP-Server-Entwicklung können wir die Tool-Schnittstelle definieren, die Autorisierung anbinden und Abnahmeprüfungen aufbauen. Die PromptID-Fallstudie zeigt verwandte Arbeiten an einer KI-Anwendung.

Mit der Software-QA-Checkliste vor dem Launch ordnest du die Tool-Tests in die gesamte Release-Entscheidung ein. Starte mit einem Lesezugriff, dessen Berechtigungen und Ausgabe du erklären kannst. Weise auch die Ablehnung unzulässiger Aufrufe nach. Erweitere die Schnittstelle anschließend um jeweils eine Geschäftsfunktion.