Capability-Design · MCP-first

Eine Capability ist die kleinste beschreibbare Fähigkeit eines Systems: typisiert, berechtigungsgeprüft, auditierbar und für Menschen wie für Agents gleichermaßen nutzbar. MCP-first beginnt nicht mit Screens, sondern mit diesen Fähigkeiten. Erst wenn das Capability-Set vollständig ist, entstehen Webapp, Mobile App, CLI und Agent-Interfaces als Clients darüber.

Die sieben Bausteine

MCP-first modelliert jede Fähigkeit mit sieben strukturellen Elementen.

Resources

Daten und Kontexte, die gelesen werden können. Resources liefern dem Agenten aufbereiteten Kontext, keine rohen Datenbanktabellen, sondern gefilterte, zweckgebundene Sichten auf den Systemzustand.

Tools

Aktionen, die das System ausführen kann. Jedes Tool hat ein typisiertes Input-Schema, ein Output-Schema, ein Fehler-Schema und ein Audit-Schema. Ein Tool ist das, was ein Button in der Webapp bloß darstellt.

Prompts / Workflows

Vorgefertigte Abläufe, die einen Agenten durch komplexe, mehrstufige Prozesse führen. Workflows definieren, welche Tools in welcher Reihenfolge mit welchem Kontext aufgerufen werden sollen, und wo menschliche Eingaben erwartet werden.

Policies

Regeln, Rechte, Schutzstufen und Freigabeprozesse. Policies entscheiden, wer eine Capability sehen, aufrufen und autonom ausführen darf. Sie sind keine Schicht, die man nachzieht, sie sind Teil der Capability-Definition.

Audit Events

Jede Aktion erzeugt einen Audit-Eintrag: wer, was, wann, mit welcher Freigabe, mit welchem Ergebnis. Audit Events sind keine optionale Betriebserweiterung, sondern Pflichtbestandteil jeder Capability.

Human Confirmation Gates

Mechanismen, bei denen der Agent den Benutzer aktiv um Bestätigung bitten muss, bevor eine Aktion ausgeführt wird. Confirmation Gates sind deklarativ in der Capability hinterlegt, nicht ad hoc im UI implementiert.

Risk Metadata

Jede Capability trägt eine Risikostufe: low, medium, high, critical oder forbidden_for_ai. Diese Metadaten steuern Discovery-Filterung, Confirmation-Pflicht und Step-up-Auth, und sind maschinenlesbar im Tool-Contract verfügbar.

Was jede Entität anbieten sollte

Unabhängig von der Fachdomäne braucht jede Entität einen konsistenten Basissatz an Capabilities.

Basis-Capabilities pro Entität

entity.list Gefilterte Liste zurückgeben
entity.search Volltextsuche mit Scoping
entity.get Einzelne Entität mit Kontext
entity.create Neue Entität anlegen
entity.update Felder ändern, idempotent
entity.archive Deaktivieren statt löschen
entity.audit Änderungshistorie abrufen
entity.permissions Effektive Rechte abfragen
entity.related Verknüpfte Entitäten laden
entity.recommended_next_actions Agentenfähige Handlungsvorschläge

Action Layer zuerst

Jede Funktion wird zuerst als Action im zentralen Action Layer implementiert. Erst danach entsteht der jeweilige Interface-Adapter.

Action: create_project

Genutzt von:
  Webapp
  Mobile App
  MCP Tool
  Worker
  CLI

Dadurch gibt es keine Doppelimplementierung: Wenn eine Webapp-Schaltfläche create_project aufruft und ein Agent dasselbe tut, nutzen beide denselben Code, dieselben Validierungen, dieselben Audit Events.

Build capabilities once. Expose them everywhere.

Zentraler Claim

Der MCP-Server ist ein Adapter

Der MCP-Server enthält keine Business Logic. Er ist ein dünner Adapter zwischen dem Agenten-Client und dem Action Layer.

Seine Aufgaben:

Discovery, welche Tools und Resources gibt es in diesem Kontext?
Schema Exposure, typisierte Beschreibung von Inputs, Outputs und Fehlern
Auth Context Mapping, Token des Clients auf User- und Tenant-Kontext abbilden
Policy Checks, darf dieser Agent dieses Tool in diesem Kontext aufrufen?
Audit Logging, Execution-Events für jede Tool-Ausführung schreiben

Typisierte In- und Outputs

Jedes Tool definiert vier Schemas:

Schema	Zweck
Input Schema	Welche Parameter erwartet das Tool, welche Typen, welche Required-Felder?
Output Schema	Was gibt das Tool bei Erfolg zurück?
Fehler-Schema	Welche Fehlercodes sind möglich, `permission_denied`, `confirmation_required`, `policy_violation`?
Audit-Schema	Was wird in das Audit Event geschrieben?

Keine losen JSON-Strukturen. Agents, wie auch Compiler und Tests, verlassen sich auf diese Schemas. Untypisierte Outputs erzwingen Ratelogik auf Clientseite.

Idempotenz

Viele Tools sollten idempotent sein: bei gleicher Anfrage dasselbe Ergebnis liefern, ohne unnötige Duplikate zu erzeugen.

create_download_link(fileId, expiresAt)

Wenn für fileId bereits ein gültiger Link mit identischem expiresAt existiert, wird der bestehende Link zurückgegeben, kein zweiter wird erstellt. Das reduziert Agent-Fehler bei Retries und macht Workflows robuster gegen Netzwerkunterbrechungen.