# Server Contracts: Fähigkeiten stabil veröffentlichen > MCP-Verträge so gestalten, dass Hosts Fähigkeiten entdecken, sicher verstehen und kontrolliert über Änderungen hinweg nutzen können. Track: [MCP Engineering](https://physar.tech/learn/mcp-engineering) Kanonische Fassung: https://physar.tech/learn/mcp-engineering/server-contracts Stand: 2026-07-25 Interaktiver Teil: 11 Checks (nur im Browser) ## Server Contracts: eine Fähigkeit ist mehr als ein Endpunkt ### 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. _[Abbildung: Die veröffentlichte Capability bleibt eine schmale, stabile Grenze zwischen internem Backend und Host-Policy.]_ | | | | --- | --- | | 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 | > **Merksatz:** Ein guter Vertrag schützt **beide** Seiten vor unnötiger Kopplung: Der Server darf sich intern ändern, der Host bekommt eine verlässliche Bedeutung. ### 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 > **Cache ist kein Freifahrtschein:** Ein Cache darf Latenz sparen. Er darf jedoch keine dauerhafte Annahme erzeugen, dass ein Server nach einem Update weiterhin dieselbe Capability anbietet. ### 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 | > **Wichtige Grenze:** JSON Schema beschreibt eine Form, keine Release-Policy. MCP schreibt keine allgemeine Versionierungs- oder Deprecation-Strategie vor; der Server muss seine Kompatibilitätszusage bewusst gestalten. ### 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 | > **Nicht jede URI ist ein Netzwerklink:** MCP lässt unterschiedliche URI-Schemata zu. Entscheidend ist, dass Server und Host dieselbe Identität und Lesesemantik verstehen. ### 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 | > **Produktentscheidung:** Wähle einen Prompt, wenn eine sichtbare Nutzerentscheidung und ein verständlicher Ablauf Teil des Vertrags sind — nicht nur, weil Text erzeugt wird. ### 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 > **Producer-Pflicht:** Die Protokollversion allein veröffentlicht keine optionalen Features. Der Server muss seine tatsächliche Unterstützung präzise deklarieren, damit Hosts keine versteckten Annahmen treffen müssen. ### 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 | > **Vertrauensregel:** Ein Server darf seine eigene Gefährlichkeit nicht verbindlich klassifizieren. Hinweise können nützlich sein, aber die Kontrolle muss außerhalb des Hinweises liegen. ### 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. > **Trade-off:** Lange Parallelunterstützung senkt Integrationsbruch, erhöht aber Test- und Betriebsaufwand. Eine schnelle Ablösung spart Pflege, zwingt Hosts jedoch zu koordinierten Upgrades. ### 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. > **Abgrenzung:** Wie du den Serverprozess implementierst, transportierst und testest, folgt in den nächsten Modulen. Hier trainierst du die veröffentlichte Bedeutung, auf der diese Arbeit aufbaut. ### 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. > **Ziel:** Ein MCP-Vertrag soll Funktionen auffindbar und nutzbar machen, ohne dass Discovery zu impliziter Berechtigung oder ein internes Detail zu einer dauerhaften externen Zusage wird. ## Quellen - modelcontextprotocol.io/specification/2025-11-25/server/tools — https://modelcontextprotocol.io/specification/2025-11-25/server/tools - modelcontextprotocol.io/specification/2025-11-25/server/resources — https://modelcontextprotocol.io/specification/2025-11-25/server/resources - modelcontextprotocol.io/specification/2025-11-25/server/prompts — https://modelcontextprotocol.io/specification/2025-11-25/server/prompts - modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle — https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle - modelcontextprotocol.io/specification/2025-11-…utilities/completion — https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion - modelcontextprotocol.io/specification/2025-11-…utilities/pagination — https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination - json-schema.org/draft/2020-12/json-schema-validation — https://json-schema.org/draft/2020-12/json-schema-validation - Model Context Protocol — Server Features: Tools und inputSchema - JSON Schema — Validation: das Keyword „required“ - API-Evolution: additive, optionale Änderungen als Kompatibilitätsregel