Skip to content

MCP-Tool-Schemas versionieren und Änderungen erkennen

Ein MCP-Server kann fehlerfrei starten und trotzdem unbemerkt seinen Vertrag mit dem KI-Client verändern. Ein versionierter Snapshot des Tool-Katalogs macht solche Änderungen im Code-Review sichtbar, bevor alte Prompts, Agenten oder Automationen daran scheitern.

Moritz Klaßen

Moritz Klaßen

Entwickler & Gründer von Klassen AI

7 Min. Lesezeit

Eine verbreitete Annahme lautet: Änderungen an einem MCP-Tool fallen beim nächsten Start sofort auf. Das ist zu optimistisch. Ein Server kann technisch einwandfrei laufen, obwohl ein Tool umbenannt wurde, plötzlich einen zusätzlichen Pflichtparameter verlangt oder mit einer neuen Beschreibung ganz anders vom Modell eingeordnet wird.

Für solche Änderungen lohnt sich ein kleiner Tooling-Schritt: Speichere den bereinigten MCP-Tool-Katalog als versionierte Datei im Repository. Der daraus entstehende Diff zeigt im Code-Review, ob sich der Vertrag zwischen Server und Client verändert hat. Du musst dafür weder produktive Aufrufe mitschneiden noch einen vollständigen Integrationstest bauen.

Der Tool-Katalog ist eine Schnittstelle

Bei der Tool-Erkennung liefert ein MCP-Server dem Client unter anderem Namen, Beschreibungen und Eingabeschemas seiner verfügbaren Tools. Diese Angaben wirken zusammen. Das Schema bestimmt, welche Argumente zulässig oder erforderlich sind. Name und Beschreibung helfen dem Modell bei der Entscheidung, wann und wofür es ein Tool verwenden soll.

Damit unterscheidet sich ein MCP-Tool-Vertrag von einer klassischen Funktionssignatur. Eine geänderte Beschreibung kann das Laufzeitverhalten beeinflussen, obwohl sämtliche Parameter gleich geblieben sind. Das Modell könnte das Tool seltener auswählen, mit einem anderen Tool verwechseln oder für einen zu breiten Anwendungsfall einsetzen.

Ein normaler Starttest erkennt solche Verschiebungen nicht. Er bestätigt lediglich, dass der Server startet und einen formal lesbaren Katalog ausliefert. Ein Snapshot macht dagegen sichtbar, was der Server aktuell anbietet.

Was in den Snapshot gehört

Ein Contract Snapshot ist eine gespeicherte, reproduzierbare Darstellung der öffentlich angebotenen Tools. Er sollte nur Felder enthalten, die für Clients relevant sind. Je nach Server gehören dazu:

  • der eindeutige Name jedes Tools,
  • die vollständige Beschreibung,
  • das Eingabeschema mit Typen, Pflichtfeldern und erlaubten Werten,
  • ein Ausgabeschema, sofern dein Server eines veröffentlicht,
  • Annotationen oder Hinweise zu Seiteneffekten, wenn Clients diese auswerten.

Laufzeitdaten haben darin nichts verloren. Zeitstempel, Prozess-IDs, zufällig erzeugte Kennungen oder umgebungsabhängige Pfade produzieren bei jedem Durchlauf einen neuen Diff, ohne eine fachliche Änderung anzuzeigen. Nach wenigen Fehlalarmen wird die Prüfung ignoriert. Das ist die übliche Karriere einer schlecht vorbereiteten Snapshot-Datei.

Auch die Reihenfolge sollte stabil sein. Sortiere Tools beispielsweise nach ihrem Namen und Objektfelder nach einem festen Verfahren. Zeilenumbrüche kannst du vereinheitlichen. Inhaltliche Texte solltest du dagegen nicht aggressiv normalisieren: Wenn eine Beschreibung geändert wurde, soll der Diff genau das zeigen.

So baust du den Snapshot-Workflow auf

Der Ablauf benötigt keinen bestimmten MCP-Client und kein bestimmtes Framework. Entscheidend ist, dass du die Tool-Liste reproduzierbar abrufst und vor dem Speichern bereinigst.

  1. Rufe den Tool-Katalog mit einer festen Entwicklungskonfiguration ab. Verwende dieselben aktivierten Module und Feature-Schalter, die für den geprüften Vertrag gelten. Produktive Zugangsdaten oder echte Geschäftsdaten sind dafür nicht erforderlich.
  2. Extrahiere nur vertragsrelevante Felder. Entferne Transportinformationen und dynamische Metadaten, sofern sie für Clients keine Bedeutung haben.
  3. Erzeuge eine kanonische Darstellung. Sortiere die Tools nach Namen, verwende eine feste Einrückung und vereinheitliche die Schlüsselreihenfolge. Sortiere Arrays nicht blind, weil ihre Reihenfolge je nach Inhalt eine Bedeutung haben kann.
  4. Speichere die Datei im Repository. Ein Pfad wie „tests/contracts/mcp-tools.json“ macht deutlich, dass es sich um eine prüfbare Schnittstelle und nicht um eine beliebige Exportdatei handelt.
  5. Erzeuge den Snapshot bei Änderungen erneut. In der Continuous Integration, also der automatisierten Prüfung eines Branches, vergleichst du die erzeugte Datei mit dem eingecheckten Stand.

Eine vereinfachte Datei kann so aussehen:

{
  "tools": [
    {
      "name": "invoice.find",
      "description": "Findet eine Rechnung anhand ihrer Rechnungsnummer.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "invoiceNumber": {
            "type": "string"
          }
        },
        "required": [
          "invoiceNumber"
        ]
      }
    }
  ]
}

Die konkrete Struktur darf zu deinem Server passen. Wichtig sind Reproduzierbarkeit und Lesbarkeit. Ein Reviewer sollte im Diff erkennen können, ob sich ein Tool-Name, ein Pflichtfeld oder eine Beschreibung geändert hat, ohne zuerst einen generierten Datenberg zu entschlüsseln.

Ein geänderter Snapshot ist noch kein Fehler

Snapshot-Tests werden schnell lästig, wenn jede Abweichung reflexartig als kaputter Build behandelt wird. Der Diff ist zunächst ein Prüfsignal. Ob die Änderung problematisch ist, hängt von ihrer Wirkung auf bestehende Clients ab.

Inkompatible Änderungen

Eine Änderung ist typischerweise inkompatibel, wenn vorhandene Aufrufe anschließend nicht mehr gültig sind. Dazu gehören insbesondere:

  • das Entfernen oder Umbenennen eines Tools,
  • das Umbenennen eines bestehenden Parameters,
  • ein neues Pflichtfeld ohne belastbaren Standardwert,
  • ein geänderter Parametertyp,
  • eine Einschränkung bisher erlaubter Werte,
  • eine grundlegend veränderte Bedeutung bei gleichbleibendem Namen.

Angenommen, „invoice.find“ akzeptiert bisher eine Rechnungsnummer als Text. Wird der Parameter ohne Übergangsphase in eine interne numerische ID geändert, bleibt der Server möglicherweise vollständig funktionsfähig. Bestehende Prompts, gespeicherte Abläufe oder Clients verwenden aber weiterhin die Rechnungsnummer. Der Snapshot-Diff zeigt diese Vertragsänderung unmittelbar.

Verhaltensrelevante Änderungen

Änderungen an Name und Beschreibung verdienen eine eigene Prüfung. Sie müssen keinen Aufruf formal ungültig machen, können aber die Tool-Auswahl durch das Modell verschieben.

Wird aus „Findet eine Rechnung anhand ihrer Rechnungsnummer“ beispielsweise „Sucht Rechnungsdaten“, ist der Text kürzer, aber auch ungenauer. Unklar bleibt nun, welche Suchkriterien unterstützt werden und ob das Tool nur liest oder weitere Aktionen ausführt. Ein reiner Schemavergleich würde dieses Problem nicht angemessen bewerten.

Prüfe deshalb, ob die neue Beschreibung Zweck, Voraussetzungen und Grenzen weiterhin verständlich ausdrückt. Eine Beschreibung ist Teil der Steuerung des KI-Clients, keine interne Entwicklernotiz.

Kompatible Erweiterungen

Ein zusätzliches optionales Feld kann kompatibel sein, solange alte Aufrufe weiterhin dasselbe Ergebnis liefern. Auch ein neues Tool verändert bestehende Signaturen nicht automatisch. Trotzdem sollte die Erweiterung bewusst geprüft werden: Ein weiteres ähnlich beschriebenes Tool kann die Auswahl schwieriger machen oder einen bisher eindeutigen Anwendungsfall aufteilen.

Kompatibilität bedeutet daher nicht, dass du den Diff ungesehen akzeptieren kannst. Sie bedeutet lediglich, dass bestehende Aufrufe voraussichtlich nicht an der neuen Vertragsform scheitern.

Diese Fragen gehören ins Code-Review

Wenn sich der Snapshot ändert, sollte der Pull Request die fachliche Absicht erklären. Der Reviewer kann den Diff anschließend mit wenigen konkreten Fragen einordnen:

  • Bleiben bestehende Tool-Namen und Parameter gültig?
  • Wurde ein optionales Feld versehentlich zum Pflichtfeld?
  • Beschreibt der Text weiterhin eindeutig, wann das Tool verwendet werden soll?
  • Werden Seiteneffekte wie Erstellen, Ändern oder Löschen erkennbar benannt?
  • Kann ein neues Tool mit einem vorhandenen Tool verwechselt werden?
  • Müssen Client, Prompt oder gespeicherter Workflow gemeinsam mit dem Server angepasst werden?
  • Benötigt die Änderung eine Übergangsphase mit altem und neuem Vertrag?

Damit wird aus „Snapshot aktualisiert“ eine nachvollziehbare Schnittstellenentscheidung. Das Einchecken der neuen Datei darf nicht die Erklärung ersetzen. Sonst bestätigt der Commit nur, dass sich etwas geändert hat. Weshalb die Änderung sicher ist, bleibt offen.

Warum ein Rohdump meist ungeeignet ist

Den vollständigen Rückgabewert der Tool-Erkennung unverändert ins Repository zu schreiben, wirkt zunächst bequem. Häufig enthält er jedoch Daten, die nichts über den Vertrag aussagen. Schon eine andere Sortierung oder eine zusätzliche Servermetadaten-Zeile kann dann den gesamten Snapshot verändern.

Die bessere Grenze lautet: Speichere alles, was ein Client für Auswahl und Aufruf eines Tools benötigt, und entferne den Rest. Diese Filterung sollte selbst im Code liegen. Eine manuell bereinigte Datei ist anfällig dafür, dass Änderungen übersehen oder versehentlich beschönigt werden.

Vermeide außerdem einen einzigen riesigen Snapshot für mehrere fachlich unabhängige MCP-Server. Kleine, klar zugeordnete Vertragsdateien erzeugen verständlichere Diffs. Sie lassen sich den verantwortlichen Modulen oder Teams zuordnen und bei Bedarf getrennt ausrollen.

So führst du die Prüfung ohne Dauerfrust ein

Für die erste Einführung eignet sich ein berichtender Modus. Die Automatisierung erzeugt den aktuellen Katalog und zeigt einen Diff an, lässt den Build zunächst aber weiterlaufen. So erkennst du, ob deine Normalisierung stabil ist oder noch unnötige Abweichungen produziert.

Sobald der Snapshot reproduzierbar bleibt, kann eine ungeprüfte Änderung den Build stoppen. Die beabsichtigte Aktualisierung erfolgt dann im selben Pull Request wie die Serveränderung. Dadurch sieht der Reviewer alten und neuen Vertrag zusammen mit dem auslösenden Code.

Lege außerdem fest, wer Vertragsänderungen freigibt. Bei einem internen Hilfstool genügt möglicherweise das normale Code-Review. Wenn mehrere Agenten oder Automationen denselben MCP-Server verwenden, sollte mindestens eine Person die Auswirkungen auf diese Verbraucher beurteilen können. Der Snapshot liefert dafür den Befund, aber keine automatische fachliche Entscheidung.

Was der Snapshot nicht prüfen kann

Der gespeicherte Katalog zeigt nur den veröffentlichten Vertrag. Er beweist nicht, dass ein Tool korrekte Ergebnisse liefert, Berechtigungen richtig durchsetzt oder Seiteneffekte zuverlässig verarbeitet. Dafür brauchst du weiterhin gezielte Funktions- und Integrationstests.

Auch die Qualität einer Beschreibung lässt sich nicht vollständig automatisieren. Ein Diff macht die Änderung sichtbar; ob der neue Text präziser oder missverständlicher ist, muss ein Mensch beurteilen. Gleiches gilt für zwei formal unterschiedliche Tools, die fachlich fast dasselbe erledigen.

Der Nutzen des Snapshots liegt deshalb in einer eng definierten Aufgabe: Er verhindert, dass Änderungen an der sichtbaren MCP-Schnittstelle unbemerkt im normalen Implementierungsdiff verschwinden.

Fazit

Ein laufender MCP-Server garantiert keinen stabilen Tool-Vertrag. Wenn du den bereinigten Tool-Katalog versionierst, werden umbenannte Tools, neue Pflichtfelder und veränderte Beschreibungen schon im Code-Review sichtbar.

Der Workflow bleibt überschaubar: Katalog abrufen, relevante Felder normalisieren, Snapshot einchecken und Abweichungen bewusst einordnen. Damit behandelst du MCP-Tools wie die Schnittstellen, die sie für Clients und Agenten tatsächlich sind.

Häufige Fragen

Kurz beantwortet, damit du schneller einschätzen kannst, was für dein Projekt wichtig ist.

Wie oft sollte ich den MCP-Tool-Snapshot aktualisieren?

Aktualisiere ihn immer zusammen mit einer beabsichtigten Änderung am veröffentlichten Tool-Vertrag. Die neue Snapshot-Datei gehört in denselben Pull Request wie der auslösende Code.

Soll jede geänderte Tool-Beschreibung den Build stoppen?

Die Änderung sollte mindestens sichtbar werden. Ob sie den Build dauerhaft stoppt, hängt von deinem Workflow ab. Wichtig ist, dass Beschreibungsänderungen geprüft werden, weil sie die Tool-Auswahl des Modells beeinflussen können.

Ersetzt der Snapshot Integrationstests für MCP-Tools?

Nein. Der Snapshot prüft Namen, Beschreibungen und Schemas. Er bestätigt weder korrekte Ergebnisse noch Berechtigungen, Fehlerbehandlung oder Seiteneffekte eines tatsächlichen Tool-Aufrufs.

Kann ich statt des Snapshots nur generierte Typen vergleichen?

Generierte Typen können Schemaänderungen sichtbar machen, erfassen aber häufig nicht den vollständigen Vertrag. Beschreibungen, Annotationen und andere für die Tool-Auswahl relevante Angaben sollten deshalb separat erhalten bleiben.