---
title: "NestJS MCP in bestehende Apps: Setup, Guards, Tests"
canonical: https://wavect.io/de/blog/nestjs-mcp-existing-app/
language: de
description: "NestJS MCP in bestehende Apps integrieren: NestJS 12 prüfen, Tools und Guards anbinden, mcp-nest migrieren und zehn Integrationstests selbst ausführen."
image: "https://wavect.io/img/blog/headers/header_nestjs-mcp-existing-app.png"
author: ["Kevin Riedl"]
published: "2026-11-04"
updated: "2026-11-04"
reviewed: "2026-11-04"
---

# NestJS MCP: Offizielles Modul in bestehende Apps integrieren

[**Zurück**](/de/blog/overview/)

[![Kevin Riedl](/img/team/kevin.webp)](/de/team/kevin-riedl/)

[Kevin Riedl](/de/team/kevin-riedl/) https://linkedin.com/in/wsdt

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

[**Weiter**](/de/blog/enterprise-mcp-authorization-architecture/)

TL;DR

Mit dem offiziellen @nestjs/mcp-Modul werden Provider-Methoden deiner bestehenden Anwendung zu Tools, Ressourcen und Prompts. Version 0.0.2 setzt laut Peer-Dependencies NestJS 12 und MCP SDK 2.4 voraus. Lass Berechtigungen in den Anwendungsservices, passe Guards an den MCP-Kontext an und teste das Protokollverhalten getrennt von der HTTP-Route. Unser Testprojekt mit synthetischen Rechnungsdaten bestand acht Prüfungen im Speicher und zwei über echtes HTTP. Beginne mit einem Lesezugriff. Vor Schreiboperationen müssen Autorisierung und Wiederholungsverhalten feststehen.

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](https://github.com/nestjs/mcp/blob/0.0.2/README.md) 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](https://docs.nestjs.com/observability/mcp-server).

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](https://github.com/nestjs/mcp/blob/0.0.2/package.json) nennt die folgenden Versionsanforderungen. Unser Testprojekt prüft eine konkret festgelegte Kombination innerhalb dieser Bereiche.

| Abhängigkeit oder Laufzeit | Versionsanforderung oder dokumentierte Schema-Unterstützung | Was du prüfen solltest |
| --- | --- | --- |
| `@nestjs/common` und `@nestjs/core` | `^12.0.0` | Halte Framework, HTTP-Adapter und Testpakete auf zueinander passenden Versionen. |
| `@modelcontextprotocol/server` | `^2.4.0` | Das ist das v2-Serverpaket. Ältere Imports aus dem gemeinsamen SDK passen dazu nicht automatisch. |
| Node.js | `>=20.19.0` für dieses Modul | Prüfe zusätzlich die Engine-Anforderungen aller weiteren Abhängigkeiten. |
| Zod | 4.2 oder neuer | Prüfe die Auswirkungen auf vorhandene Zod-3-Schemas vor dem Versionswechsel. |
| `@modelcontextprotocol/client` | Optionaler Peer `^2.4.0` | Für die Clienttests im Speicher brauchst du dieses Paket. |
| Paketformat | ESM-Exports | Prüfe das Zusammenspiel mit Build und Laufzeit deiner Anwendung. |

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

npm install --save-exact @nestjs/mcp@0.0.2 \
  @modelcontextprotocol/server@2.4.0 zod@4.6.7

npm install --save-dev --save-exact @modelcontextprotocol/client@2.4.0
```

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](https://github.com/nestjs/mcp/blob/0.0.2/lib/utils/schema.util.ts). 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](https://github.com/nestjs/mcp/blob/0.0.2/lib/services/mcp-registry.service.ts) 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](https://docs.nestjs.com/mcp/primitives) beschreibt Decorators und Rückgabewerte. Für eine Anwendung zur Rechnungsbearbeitung würden wir die Aufgaben so aufteilen:

| Aufgabe des Clients | MCP-Baustein | Umsetzung in der Anwendung |
| --- | --- | --- |
| Status einer freigegebenen Rechnung abfragen | `@Tool()` mit `inputSchema` | Gezielte Abfrage über die bestehende Zugriffsprüfung. |
| Veröffentlichte Abrechnungsregeln lesen | `@Resource()` mit `uri` | Versionierte Referenzdaten mit klar festgelegtem Empfängerkreis. |
| Eine berechtigte Rechnung per URI lesen | `@ResourceTemplate()` mit `uriTemplate` | Dieselbe Berechtigung auf Datensatzebene prüfen wie beim Abfrage-Tool. |
| Vorlage für eine Support-Antwort vorbereiten | `@Prompt()` mit `argsSchema` | Nachrichten für den Client zurückgeben. Ein späterer Versand braucht eine eigene Autorisierung. |

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](https://github.com/nestjs/mcp/blob/0.0.2/lib/context/mcp-execution-context.ts) 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](https://github.com/nestjs/mcp/blob/0.0.2/lib/interfaces/mcp-context.interface.ts). 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](https://github.com/nestjs/mcp/blob/0.0.2/lib/auth/mcp-auth-gate.ts) 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](/de/blog/enterprise-mcp-authorization-architecture/) 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](https://github.com/nestjs/mcp/blob/0.0.2/tests/authentication.e2e.spec.ts) 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](https://docs.nestjs.com/mcp/transports) beschreibt die verfügbaren Möglichkeiten:

| Verbindung | Unterstütztes Verhalten | Was du gesondert prüfen musst |
| --- | --- | --- |
| HTTP, Clients für 2026-07-28 | Unabhängige Anfragen, JSON- oder SSE-Antworten und unterstützte Abläufe mit angeforderter Benutzereingabe. | OAuth, Proxy-Routing, erlaubte Origins, Größenlimits und die tatsächliche Funktionsunterstützung des Clients. |
| HTTP, ältere Clients von 2025 | Gewöhnliche Aufrufe über denselben zustandslosen Endpunkt. | Interaktive Elicitation, die eine Server-zu-Client-Sitzung benötigt, steht nicht zur Verfügung. |
| Stdio | Ein Client startet den Serverprozess; beide Protokollgenerationen werden unterstützt. | Kein HTTP-Request und keine Durchsetzung von HTTP-OAuth-Scopes. Lege lokale Identität und Berechtigungen ausdrücklich fest. |

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](/de/blog/mcp-stateless-server-migration-2026/) 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](https://docs.nestjs.com/mcp/migration).

| Bisherige Integration | Änderung im offiziellen Modul | Konsequenz für deine Prüfung |
| --- | --- | --- |
| Imports aus `@modelcontextprotocol/sdk` | Die v2-API von `@modelcontextprotocol/server` verwenden. | Prüfe Typen und weitere Nutzer der alten Abhängigkeit, bevor du sie entfernst. |
| `parameters` | `inputSchema` bei Tools; `argsSchema` bei Prompts. | Prüfe veröffentlichte Schemas und die Ablehnung ungültiger Argumente. |
| `mcpEndpoint` und die Moduloption `guards` | `path` und `decorators` am Endpunkt. | Unterscheide Guards auf Routenebene von der Autorisierung am Provider. |
| `@McpController()` und Strategy-Bootstrap aus 2.x | Gewöhnliche injizierbare Provider und der Anwendungs-Bootstrap. | Verschiebe Klassen nach `providers`. Prüfe andere Microservices, bevor du ihren Bootstrap entfernst. |
| Auslesen des RPC-Kontexts | `McpExecutionContext`. | Passe gemeinsam genutzte Guards, Interceptors und Filters an. |
| Eingebauter Authorization Server | Externer Identity Provider und ein Verifier. | Token-Ausstellung und Client-Anmeldung benötigen eine eigene Migration. |
| Provider mit Request-Scope oder Registrierung zur Laufzeit | In dieser Version nicht unterstützt. | Ändere den Entwurf oder behalte die bisherige Integration, bis die Voraussetzungen passen. |

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](https://github.com/nestjs/mcp/blob/0.0.2/lib/testing/index.ts) 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`.

| Testebene | Was du prüfst | Was einen weiteren Test braucht |
| --- | --- | --- |
| Direkter Service- oder Provider-Test | Fachliche Entscheidungen, zurückgegebene Felder und Transaktionsverhalten. | Protokollpipeline und HTTP-Route. |
| MCP-Client im Speicher | Erkennung, Ein- und Ausgabeverträge, Token-Prüfungen, Scopes, Provider-Guards und Ergebnisstruktur. | HTTP-Middleware, Endpunkt-Guards, echte CORS-Preflight-Anfragen, Proxys und Body-Parser. |
| Echtes HTTP und der vorgesehene Client | OAuth-Discovery-Challenge, Routing, Browserverhalten, Verbindungsbehandlung und Client-Kompatibilität. | Für jede fachliche Änderung bleibt eine ausdrückliche Prüfung des resultierenden Zustands erforderlich. |

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](https://docs.nestjs.com/mcp/testing) 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](/downloads/nestjs-mcp-existing-app-fixture.zip).

| Ausgeführte Prüfung | Beobachtetes Ergebnis |
| --- | --- |
| Tool-Erkennung | Das vorgesehene Tool wurde mit seinen Ein- und Ausgabeschemas aufgelistet. |
| Berechtigte Abfrage | Die strukturierten Daten enthielten `inv_demo` und `open`. |
| Ungültige Eingabe | Tool-Fehler; die Anzahl der Aufrufe des Rechnungsservices blieb unverändert. |
| Anderer Mandant mit gültigem Token | Die angefragte Rechnung war nicht verfügbar. |
| Fehlender Scope | `InsufficientScopeError`; kein Service-Aufruf. |
| Falsche Abteilung | Der Provider-Guard lehnte den Aufruf ab; kein Service-Aufruf. |
| Fehlendes Token | Die Client-Verbindung wurde abgelehnt. |
| Ältere Client-Protokollgeneration | Der berechtigte Lesezugriff lieferte ein erfolgreiches Ergebnis. |
| Echte HTTP-Anfrage ohne Authentifizierung | 401 mit einer OAuth-Challenge für die Ressourcenmetadaten. |
| Nicht erlaubte Browser-Origin über HTTP | 403. |

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](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/). `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](/de/blog/mcp-security-boundary-data-level-access-control/) 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](/de/services/nestjs-development/) umfasst die dafür nötigen Änderungen an deiner Anwendung. Mit unserer [MCP-Server-Entwicklung](/de/services/mcp-server-development/) können wir die Tool-Schnittstelle definieren, die Autorisierung anbinden und Abnahmeprüfungen aufbauen. Die [PromptID-Fallstudie](/de/case-studies/promptid/) zeigt verwandte Arbeiten an einer KI-Anwendung.

Mit der [Software-QA-Checkliste vor dem Launch](/de/software-development-guide/software-qa-checklist-before-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.

## Häufige Fragen zur NestJS-MCP-Integration

### Braucht @nestjs/mcp einen LLM-API-Key?

Das MCP-Modul stellt einem Client Funktionen deiner Anwendung bereit. Um Tools, Ressourcen oder Prompts anzubieten, benötigt es keinen LLM-API-Key. Der Assistent oder Agent, der diese Funktionen nutzt, kann eigene Modellzugänge und Kosten haben. Ruft ein Tool selbst ein Modell auf, entsteht diese zusätzliche Abhängigkeit durch deinen Anwendungscode.

### Kann der MCP-Endpunkt neben meiner REST-API laufen?

Ja. Das offizielle Modul ergänzt die bestehende Nest-Anwendung um einen HTTP-Endpunkt, standardmäßig unter /mcp. Globales Präfix und Endpunktversionierung können die endgültige Route verändern. Halte REST-Controller und MCP-Provider so schlank, dass beide dieselben Anwendungsservices aufrufen. Ändert sich deren gemeinsames Verhalten, teste beide Zugangswege.

### Bleiben Tools für Aufrufer ohne passenden Scope unsichtbar?

Nein. Ein Scope begrenzt die Ausführung, nicht die Sichtbarkeit der Tool-Definition. Schreibe keine Geheimnisse, Kundennamen oder sensiblen Betriebsdetails in Tool-Namen und Beschreibungen unter der Annahme, dass ein Aufrufer ohne ausreichende Scopes sie nicht auflisten kann. Der Zugriff auf einzelne Datensätze muss weiterhin bei der Ausführung autorisiert werden.

### Kann ein MCP-Provider einen Mandantenservice mit Request-Scope nutzen?

Die geprüfte Version lehnt Abhängigkeitsbäume mit Request-Scope bei der Erkennung ab. Wenn deine Anwendungsservices es unterstützen, kannst du den verifizierten Mandanten und Akteur stattdessen über Aufrufargumente übergeben. Prüfe die gesamte Abhängigkeitskette. Auch ein scheinbarer Singleton-Provider kann weiter unten von Zustand mit Request-Scope abhängen.

### Macht der Abbruch eines Aufrufs einen abgeschlossenen Schreibzugriff rückgängig?

Ein Abbruch kann eine bereits gespeicherte Änderung nicht von sich aus zurücknehmen. Gib das AbortSignal des Aufrufs an Operationen weiter, die Abbrüche unterstützen. Unterscheide zwischen einem Abbruch vor dem Commit und einer verlorenen Antwort nach dem Commit. Mit einem dauerhaft gespeicherten Vorgang kann der Aufrufer das Ergebnis wiederfinden. Rollback oder Kompensation brauchen einen eigenen Entwurf in der Anwendung.

### Ist das der MCP-Server von NestJS Observe?

Nein. Mit diesem Paket baust du eine MCP-Schnittstelle für deine eigene Anwendung. Der MCP-Server von NestJS Observe stellt Funktionen des Observability-Produkts bereit. Ein Suchtreffer über die Verbindung eines Assistenten mit Observe erklärt nicht, wie du einen eigenen Provider registrierst, einen Rechnungsvorgang absicherst oder eine Community-Integration für NestJS MCP migrierst.

### Kann ein Prompt die Berechtigung für ein Schreib-Tool erteilen?

Ein Prompt liefert Anweisungen oder Nachrichten an den Client. Die Berechtigung ergibt sich weiterhin aus authentifizierter Identität, konfigurierten Scopes und der Autorisierung durch die Anwendung zum Ausführungszeitpunkt. Auch wenn der Client eine menschliche Bestätigung einholt, musst du diese an die vorgesehene Operation und ihre Eingaben binden. Prüfe den Zugriff erneut, bevor der Service gespeicherte Daten verändert.

Architektur und Plattformen

## Weiterlesen

Framework-, Plattform- und Systementscheidungen mit langfristiger Delivery-Wirkung.

[Hier starten**Smart-City-Architektur: MQTT, LoRaWAN, Kubernetes und Terraform**](/de/blog/smart-city-architecture-best-practices-2026/)

- [Figma Weave und Figma Design: Welche Verbindung passt?](/de/blog/figma-weave-design-workflow/)
- [Craft Anything: So prüfst du einen Website-Nachbau](/de/blog/craft-anything-website-rebuild-verification/)
- [OpenMontage: Videoproduktion mit deinem Coding-Agenten](/de/blog/openmontage-ai-video-production-review/)
- [Mireye Land Search API: MCP, Preise und Grundstückssuche](/de/blog/mireye-land-search-enrich-api-mcp/)
- [git-ai: Parallele Agenten-Merges und Verifikation](/de/blog/git-ai-concurrent-agents-merge-verification/)

[Nächster Artikel**Figma Weave und Figma Design: Welche Verbindung passt?**](/de/blog/figma-weave-design-workflow/)

[**Zurück**](/de/blog/overview/)

[![Kevin Riedl](/img/team/kevin.webp)](/de/team/kevin-riedl/)

[Kevin Riedl](/de/team/kevin-riedl/) https://linkedin.com/in/wsdt

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

[**Weiter**](/de/blog/enterprise-mcp-authorization-architecture/)