Server Contracts: eine Fähigkeit ist mehr als ein Endpunkt
Einführung · 10 Abschnitte · ~8 Min Lesezeit · Stand
Vom Backend zur veröffentlichten Fähigkeit
Dieses Modul setzt voraus, dass du die MCP-Rollen und Primitives kennst. Jetzt geht es um den Vertrag innerhalb eines Servers: Was darf ein Host entdecken, wie versteht er die Bedeutung einer Eingabe, und was bleibt trotz eines stabilen Namens veränderbar? Ein MCP-Vertrag ist eine absichtlich kleine, veröffentlichte Sicht auf eine Fähigkeit — nicht ein Spiegelbild der internen Datenbank, Queue oder REST-API.
| Interne Implementierung | Kann Tabellen, Jobnamen, Auth-Provider und Fehlerdetails ändern |
|---|---|
| Veröffentlichter MCP-Vertrag | Beschreibt stabile Operationen, Argumente, Ressourcen und Capability-Signale |
| Host-Policy | Entscheidet separat, was aus dem Angebot sichtbar oder ausführbar wird |
Der Vertrag beginnt mit Discovery
Tools, Resources und Prompts werden über ihre jeweiligen Listen sichtbar. Der Host kann dabei paginieren und Ergebnisse cachen. Diese Liste ist deshalb nicht bloß UI-Metadaten: Name, Beschreibung, Eingabeform und weitere veröffentlichte Felder bilden die Capability, auf die ein Host seine Auswahl, Anzeigen und Integrationslogik stützt.
- Verbindung initialisieren
- Fähigkeit und Listen-Operation feststellen
- Vollständige paginierte Liste entdecken
- Host-Policy auf den entdeckten Vertrag anwenden
- Erst danach Fähigkeit anbieten oder aufrufen
Ein veröffentlichtes Schema ist ein Kompatibilitätsversprechen
Ein Tool veröffentlicht mit inputSchema eine JSON-Schema-Beschreibung seiner Argumente. Hosts und Modelle können diese Beschreibung für Auswahl und Konstruktion verwenden. Dadurch wird die Form der Eingabe Teil des öffentlichen Vertrags: Ein neues Pflichtfeld, ein engerer Wertebereich oder dieselbe Feldbezeichnung mit neuer Bedeutung kann vorhandene Aufrufer brechen — auch wenn der Tool-Name gleich bleibt.
| Kompatibel erweitern | Optionales, klar dokumentiertes Feld hinzufügen und die bisherige Bedeutung erhalten |
|---|---|
| Breaking Change | Pflichtfeld hinzufügen, Typ oder erlaubte Werte einschränken oder Feldsemantik ändern |
| Migration | Alten Vertrag erhalten oder eine getrennte, eindeutig benannte Capability für die neue Bedeutung veröffentlichen |
Resources brauchen adressierbare Bedeutung
Eine Resource wird durch eine URI referenziert. Eine Resource Template beschreibt eine wiederverwendbare URI-Form mit Argumenten. Die URI ist damit ein Vertragsschlüssel: Sie sollte die fachliche Identität transportieren, nicht eine flüchtige interne Dateistruktur, einen zufälligen Cache-Pfad oder ein implizites URL-Routing des aktuellen Frameworks.
| Stabil | inventory://tenant/acme/services/payments steht für eine fachliche Resource |
|---|---|
| Fragil | file:///tmp/export-8472.json leakt eine temporäre Umsetzung |
| Template | Eine dokumentierte URI-Form macht variable Teile sichtbar und vervollständigbar |
Prompts sind ausgewählte Workflow-Verträge
Ein Prompt bietet einen vom Nutzer wählbaren Einstieg in einen Workflow. Er kann Argumente definieren; für Prompt- und Resource-Template-Argumente kann ein Server optional Vervollständigungen anbieten. Das ist ein interaktiver Vertrag: Argumentnamen und ihre Bedeutung müssen stabil genug sein, dass ein Host eine verständliche Auswahloberfläche und sichere Vorbelegung erzeugen kann.
| Prompt | Nutzer wählt einen benannten Workflow und füllt dessen Argumente |
|---|---|
| Completion | Server schlägt kontextuelle Werte vor, wenn die Capability ausgehandelt wurde |
| Tool | Modell kann eine Operation vorschlagen; das ist keine Prompt-Alternative nur wegen ähnlicher Parameter |
Capabilities sind veröffentlichte Zusagen des Servers
Die Initialisierung veröffentlicht Protokollversion und Client- sowie Server-Capabilities. Für einen Server ist das mehr als Dekoration: Wer tools.listChanged, resources.subscribe oder completions deklariert, signalisiert genau diese optionale Interaktion für die Verbindung. Eine implementierte, aber nicht deklarierte Funktion ist kein verlässlicher Teil des veröffentlichten Vertrags; eine deklarierte Funktion muss der Server auch tatsächlich bedienen.
- Optionale Funktion implementieren
- Passende Server-Capability in `initialize` deklarieren
- Nur zum deklarierten Vertrag passende Requests oder Notifications senden
- Bei Änderung der Unterstützung den Vertrag für neue Verbindungen korrekt aushandeln
Annotations helfen bei Darstellung, nicht bei Freigabe
Tools, Resources und Prompts können Beschreibungen und Annotations tragen. Bei Tools enthalten Annotations unter anderem Hinweise wie readOnlyHint, destructiveHint, idempotentHint oder openWorldHint. Laut Spezifikation sind diese Hinweise untrusted und unverbindlich. Sie unterstützen Ranking, Darstellung und Risikohinweise, dürfen aber keine Autorisierungs-, Approval- oder Sandbox-Policy ersetzen.
| Annotation | Hinweis für Host oder UI, etwa zur erwarteten Wirkung |
|---|---|
| Serverdurchsetzung | Tatsächliche Validierung und Berechtigung vor Ausführung |
| Host-Policy | Unabhängige Freigabe, Allowlist, Nutzerbestätigung und Kontextgrenze |
Releases brauchen einen Semantik- und Migrationsplan
MCP standardisiert die Tool-Beschreibung und Discovery, aber keine allgemeine SemVer-, Deprecation- oder Migrationspolitik für deine fachliche API. Ein Release, das ein Pflichtargument ergänzt, einen Rückgabewert anders interpretiert oder eine Wirkung erweitert, ist deshalb eine Produkt- und Kompatibilitätsentscheidung des Serverteams. list_changed kann Hosts über eine veränderte Liste informieren, löst aber keine Migration aus.
- Additiv: Neue optionale Fähigkeit mit klarer Bedeutung veröffentlichen und bestehende Aufrufe erhalten.
- Breaking: Alten Vertrag weiter bedienen oder eine getrennte Capability für die neue Semantik anbieten.
- Deprecation: Übergangszeit, Kommunikation und Entfernung bewusst im eigenen Release-Prozess festlegen.
Ein Vertrags-Review vor dem Release
Prüfe einen Serververtrag in vier Fragen: Bleibt die veröffentlichte Bedeutung unabhängig von der Backend-Implementierung? Kann ein Host vollständige Fähigkeiten entdecken und nur nach Negotiation nutzen? Werden Schema, URI und Prompt-Argumente auf beiden Seiten gleich verstanden? Und erhält jede Änderung einen expliziten Policy- und Kompatibilitätsschritt?
- Mache Namen, URIs, Argumente und Seiteneffekte für den Konsumenten verständlich.
- Halte interne IDs, Dateipfade und unkontrollierte Backend-Fehler aus dem öffentlichen Vertrag heraus.
- Kopple Vertrauensentscheidungen nie an Beschreibungen oder Annotations des Servers.
Gleich entscheidest du acht Vertragsgrenzen
Die Checks folgen derselben Linie: erst eine stabile Capability statt eines Backend-Leaks, dann Discovery und Schema, anschließend Resources und Prompts, danach präzise deklarierte Server-Capabilities, unverbindliche Annotations und bewusst migrierte Releases. Entscheidend ist jeweils nicht, was ein Server technisch senden kann, sondern welche Aussage ein Host belastbar als Vertrag verwenden darf.