Dies ist eine 10-teilige Serie darüber, wie Apidog Apidog CLI entwickelt hat: ein Befehlszeilentool für API-Tests und API-Lebenszyklusmanagement. Lesen Sie der Reihe nach oder springen Sie zu einem Beitrag, der Sie interessiert.
| # | Titel | Schwerpunkt |
|---|---|---|
| 1 | Wir haben 126 MCP-Tools entwickelt. Aber es ist nicht die beste Lösung für Agenten | Problemfindung |
| 2 | Warum wir die brandneue Apidog CLI entwickelt haben | Architekturentwicklung |
| 3 | Die goldene Regel: CLI produziert Fakten, Modell agiert auf Fakten | Kernphilosophie |
| 4 | agentHints: CLIs beibringen, mit Agenten zu kommunizieren |
Strukturierte Ausgabe |
| 5 | SKILL: Operative Erfahrung als Code ausliefern | Operative Erfahrung |
| 6 | Die Zahlen lügen nicht: 30% weniger Tool-Aufrufe, 25% weniger Tokens | Quantitative Ergebnisse |
| 7 | Vom PRD zum Testzyklus: Ein vollständiger Agenten-Workflow mit Apidog CLI | Praktische Anleitung |
| 8 | Warum CI/CD-Kompatibilität für Agenten-Tools nicht verhandelbar ist | DevOps-Perspektive |
| 9 | KI-Zweig: Sicherere Projektänderungen mit KI-Agenten | Sicherheitsebene |
| 10 | Spec-First war gestern. Willkommen bei Skill-First. | Vision & Zukunft |
Als MCP zum Branchen-Hotspot wurde, bauten wir einen vollständigen MCP-Server mit 126 generierten Tools. In der Praxis zeigte sich: Mehr Tools bedeuten nicht automatisch bessere Agenten-Workflows.
Der MCP-Hype
Anfang 2025 wurde MCP, das Model Context Protocol, zu einem zentralen Thema für Entwicklerteams, die KI-Agenten mit externen Systemen verbinden wollten.
Anthropic bewarb das Protokoll. Cursor, Claude Code, Antigravity, verschiedene Agent-IDEs und SaaS-Produkte folgten schnell. Die Erwartung war klar:
Agenten sollen über ein standardisiertes Protokoll Tools und Datenquellen verwenden können.
Damit wurde fast jedes Produkt mit einer API mit derselben Frage konfrontiert:
„Haben Sie MCP?“
Für Apidog schien die Antwort naheliegend: Ja, wir sollten unsere API-Entwicklungsfunktionen als MCP-Tools bereitstellen.
Warum MCP zuerst wie die richtige Lösung aussah
Apidog enthält viele Funktionen rund um den API-Lebenszyklus:
- API-Dokumentation
- Schema-Definitionen
- Mock-Server
- Testfälle
- Testszenarien
- Testsuiten
- Testberichte
- Import- und Export-Workflows
- Zusammenarbeit in Branches
- weitere projektbezogene Operationen
Wenn Agenten ein neuer Einstiegspunkt für Softwareprodukte werden, dann sollten sie diese Funktionen nutzen können.
Unsere ursprüngliche Annahme war:
Mehr exponierte Produktfunktionen = bessere Agenten-Aktivierung.
Konkret sollten Agenten in der Lage sein:
- API-Dokumentation abzufragen
- Testfälle zu erstellen
- Testszenarien auszuführen
- Projektdaten zu importieren oder zu exportieren
- Umgebungen und Variablen zu verwalten
- in Branches zusammenzuarbeiten
Diese Annahme war technisch plausibel. In realen Agenten-Workflows erwies sie sich jedoch als unvollständig.
Was wir gebaut haben
Apidog MCP war keine Demo mit wenigen Endpunkten. Wir bauten einen vollständigen MCP-Server mit Sitzungssystem, Tool-Kategorien und dynamischer Erkennung.
1. Sitzungssystem
Der MCP-Client initialisiert zuerst eine Sitzung. Der Server erzeugt eine sessionId und speichert den Sitzungsstatus über Redis. Nachfolgende Requests verwenden dieselbe sessionId.
Vereinfacht sieht der Ablauf so aus:
Client -> MCP Server: initialize
Server -> Client: sessionId
Client -> MCP Server: tool call + sessionId
Server -> Redis: read/update session state
Server -> Client: tool result
Das war also kein einfacher HTTP-Aufruf, sondern ein Sitzungssystem auf Protokollebene.
2. Tool-Kategorien
Wir haben die Apidog-Funktionen nicht als wenige manuelle Tools implementiert, sondern in mehrere Kategorien aufgeteilt.
| Kategorie | Beschreibung | Beispiele |
|---|---|---|
| Native Projekttouls | Projektbezogene Operationen | Projektübersichten, Ordnerstrukturen, Ressourcendetails |
| Integrierte Domänen-Tools | Kernfunktionalität von Apidog | Import/Export, Endpunkt-Details, Testfälle, Testszenarien |
| Generierte OpenAPI-Tools | Automatisch aus OpenAPI-Definitionen konvertiert | 126 Tools mit Identifier, Pfad, HTTP-Methode und Eingabe-Schema |
Die letzte Kategorie war entscheidend: 126 generierte Tools.
Jedes Tool enthielt:
- eindeutigen Identifier
- spezifischen API-Pfad
- HTTP-Methode wie
GET,POST,PUT,DELETE - vollständiges Eingabe-Schema
- Feldbeschreibungen, Typen und Enum-Werte
- definierte Rückgabestruktur
3. Progressive Offenlegung
Um nicht alle Endpunkte direkt als sichtbare Tools in den Kontext zu drücken, implementierten wir eine dynamische Erkennungsebene.
Der Agent sollte typischerweise so vorgehen:
1. listOpenApiEndpoints
-> verfügbare Endpunkt-Tools suchen
2. getOpenApiDetails
-> Details eines konkreten Tools abrufen
3. executeOpenApi
-> HTTP-Aufruf per Tool-ID ausführen
Das Ziel war progressive Offenlegung: Der Agent sollte erst suchen, dann Details laden und erst danach ausführen.
In der Praxis löste das jedoch nicht das Kernproblem.
Das eigentliche Problem: eine Wand zufälliger Tools
Nehmen wir eine typische Benutzeranfrage:
„Helfen Sie mir, einen Test für diesen Endpunkt hinzuzufügen und die Verifizierung auszuführen.“
Aus Produktsicht ist das machbar. Apidog kann:
- Endpunkte finden
- Testfälle erstellen
- Testszenarien ausführen
- Berichte generieren
Aus Agentensicht entstehen aber sofort mehrere Entscheidungspunkte.
| Entscheidungspunkt | Mögliche Optionen | Problem |
|---|---|---|
| Wo beginnen? | Erst Projekt finden? Erst Endpunkt finden? | Keine klare Reihenfolge |
| Was lesen? | Endpunkt-Details? Bestehende Testfälle? | Beides kann sinnvoll sein |
| Wie erstellen? | Direkt createTestCase? Erst Fallgruppe finden? |
Workflow ist implizit |
| Wie aktualisieren? | Direkt Update-Tool? Schritte importieren und zurücklesen? | Produktlogik ist versteckt |
Der Agent muss also nicht nur ein Tool ausführen. Er muss zuerst herausfinden, welche Tool-Kette überhaupt korrekt ist.
Das ist der Unterschied zwischen „Tools bereitstellen“ und „einen ausführbaren Prozess bereitstellen“.
Problem 1: Tool-Erkennung wird schnell teuer
Apidog lässt sich nicht mit zehn einfachen Operationen abbilden.
| Modul | Typische Operationen |
|---|---|
| Endpunkte | Auflisten, abrufen, erstellen, aktualisieren, löschen |
| Schemata | Auflisten, abrufen, erstellen, aktualisieren, löschen |
| Umgebungen | Auflisten, abrufen, erstellen, aktualisieren, löschen, Variablen verwalten |
| Mocks | Konfigurieren, aktivieren, deaktivieren |
| Testfälle | Auflisten, abrufen, erstellen, aktualisieren, löschen, duplizieren |
| Testszenarien | Auflisten, abrufen, erstellen, aktualisieren, löschen, Schritte importieren, ausführen |
| Test-Suiten | Auflisten, abrufen, erstellen, aktualisieren, löschen |
| Berichte | Auflisten, abrufen, generieren, herunterladen |
| Import/Export | Mehrere Formate und Optionen |
| Branches | Auflisten, erstellen, zusammenführen, löschen |
Sobald die Tool-Anzahl von einem Dutzend auf Dutzende oder Hunderte steigt, wird Tool-Auswahl selbst zu einer Aufgabe.
Wir versuchten, Workflows in die Tool-description zu schreiben, zum Beispiel:
„Bevor Sie Endpunkt-Daten abfragen, müssen Sie zuerst das Projekt über ein anderes Tool bestätigen, dann Projektmetadaten über ein drittes Tool abrufen und schließlich das aktuelle Tool aufrufen.“
Das funktioniert bei kleinen Tool-Sets. Bei großen Tool-Sets konkurrieren die Beschreibungen selbst um Modellaufmerksamkeit.
Je mehr Anleitung wir in description-Felder packten, desto mehr Tokens verbrauchten wir — und desto unwahrscheinlicher wurde es, dass der Agent jede Anweisung zuverlässig befolgte.
Problem 2: Geschäftsschema dringt in den Modellkontext ein
Ein MCP-Tool besteht nicht nur aus einem Namen.
Typischerweise enthält jedes Tool:
descriptioninput schema- Parameterdefinitionen
- Pflicht- und optionale Felder
- verschachtelte Strukturen
- Enum-Werte
- Rückgabestrukturen
- Fehlerformate
Eine konservative Rechnung:
| Faktor | Wert |
|---|---|
| Anzahl der Tools | 100+ |
| Durchschnittliche Tokens pro Tool | ~500 |
| Gesamtlast für Tool-Beschreibungen | ~50.000 Tokens |
Eine Benutzerfrage kann nur 50 Zeichen lang sein. Trotzdem muss das Modell zuerst sehr viel Tool-Kontext verarbeiten.
Das ist kein theoretisches Problem. Der offizielle Cursor-Beitrag Dynamic Context Discovery beschreibt, dass durch bedarfsgeladenen Kontext für MCP-Tool-Beschreibungen, Terminal-Sitzungen und lange Konversationen der Token-Verbrauch zur Laufzeit um 46,9% reduziert wurde.
Auch Trae verfolgte einen direkten Begrenzungsansatz:
- maximale Tool-Anzahl: 40
- maximale Länge einzelner Tool-Beschreibungen: 8000 Zeichen
In frühen internen Tests berichteten Teams, dass Apidog MCP bei einigen Tools in Trae nicht zuverlässig aufgerufen werden konnte. Der Agent musste wegen begrenztem Modellkontext priorisieren — externe Tools wurden dabei früh gekürzt.
Die praktische Schlussfolgerung:
Tool-Beschreibungen können nicht unbegrenzt in den Modellkontext geladen werden.
Problem 3: Protokollsitzungen machen Ausführungsketten schwerfälliger
Der Apidog MCP-Server musste mehrere Protokollzustände verwalten.
| Protokollstatus | Beschreibung |
|---|---|
| MCP initialisieren | Handshake zwischen Client und Server |
sessionId generieren |
eindeutiger Identifier für die Sitzung |
| Redis-Sitzung speichern | Persistenz des Status |
| Transport verbinden/trennen | Verbindungsmanagement |
| Sitzung berühren | Keep-Alive-Mechanismus |
| Sitzung löschen | Bereinigung nach Abschluss |
| JSON-Antwort oder SSE | unterschiedliche Ausgabeformate |
Für einzelne Tool-Aufrufe sind diese Kosten akzeptabel.
Für Agentenaufgaben mit vielen Explorationen und wiederholten Aufrufen erhöht das Zustandsmanagement jedoch die Komplexität auf Server- und Clientseite.
Bei der Implementierung mussten wir viel Aufwand in Kompatibilität und Debugging investieren, unter anderem für:
- Cursor
- Claude Code
- Antigravity
- Trae
- weitere Agenten-Clients
Trotzdem blieben Protokoll-Kompatibilitätsprobleme bestehen, während MCP selbst weiterentwickelt und gepatcht wurde.
Problem 4: Atomare Tools drücken Produktsemantik schlecht aus
Ein Testszenario in Apidog ist nicht einfach nur ein steps-Array.
Es umfasst unter anderem:
| Komponente | Komplexität |
|---|---|
| Import | Schritte aus Endpunkten oder bestehenden Fällen |
| Zurücklesen | vollständige Struktur nach Import abrufen |
| Interne Fälle | HTTP-Anfragen innerhalb von Schritten |
| Vor-/Nachbearbeiter | Skripte vor oder nach Requests |
| Assertions | Regeln zur Antwortvalidierung |
| Variablenextraktion | Werte aus Antworten erfassen |
| Laufzeitumgebung | Umgebungsauswahl und Variablen |
| Berichtsverifizierung | Testergebnisse prüfen |
Wenn diese Logik in viele atomare MCP-Tools zerlegt wird, muss der Agent die Orchestrierung selbst übernehmen.
Das Modell muss dann Fragen beantworten wie:
- Warum muss nach dem Import zurückgelesen werden?
- Warum haben interne Fälle unterschiedliche Update-Marker?
- Warum benötigen Assertions bestimmte Vergleichsoperatoren?
- Warum hat Variablenextraktion Typbeschränkungen?
Diese Details gehören eigentlich in das Engineering-System, nicht in die spontane Modellentscheidung.
Je atomarer die Tools sind, desto mehr Produktwissen muss der Agent rekonstruieren.
Die Grundursache
Alle vier Probleme haben dieselbe Ursache:
MCP verbindet Tools. Komplexe Entwicklungsaufgaben benötigen aber ausführbare technische Prozesse.
| MCP-Stärke | MCP-Einschränkung |
|---|---|
| Standardisierte Verbindung | drückt keinen vollständigen Workflow aus |
| Einheitliches Protokoll | erzwingt keine Reihenfolge |
| Tool-Exposition | validiert keine Qualität |
| Dynamische Erkennung | liefert keine fachliche Entscheidung |
Für einfache Produkte mit wenigen klaren Operationen funktioniert MCP gut. Der Agent kann ein Tool auswählen, es aufrufen und das Ergebnis verwenden.
Für Produkte wie Apidog — mit vielen Modulen, verschachtelten Strukturen, versteckten Workflows und produktspezifischer Semantik — erzeugt MCP allein eine Wand zufälliger Tools.
Was wir gelernt haben
| Lehre | Praktische Konsequenz |
|---|---|
| Mehr Tools ≠ bessere Agenten-Aktivierung | Tool-Anzahl ist ein Kostenfaktor |
| Tool-Beschreibungen konkurrieren um Kontext | 500 Tokens × 100 Tools werden schnell teuer |
| Sitzungsprotokolle erhöhen Ausführungsaufwand | jeder Aufruf trägt Protokollstatus mit |
| Atomare Tools verlangen Produktwissen | Agenten müssen interne Abläufe verstehen |
| Verbindung ≠ Ausführung | MCP verbindet; CLI + SKILL führt aus |
Für Entwicklerteams, die eigene Agenten-Integrationen bauen, ergibt sich daraus eine konkrete Checkliste:
Wenn ein Agent eine Aufgabe lösen soll:
[ ] Muss er nur ein Tool aufrufen?
[ ] Oder muss er eine Tool-Sequenz korrekt orchestrieren?
[ ] Ist die Reihenfolge explizit?
[ ] Sind Validierungsschritte definiert?
[ ] Ist Produktsemantik im System codiert?
[ ] Oder muss das Modell sie erraten?
Wenn mehrere Antworten auf „Das Modell muss es erraten“ hinauslaufen, reicht eine Tool-Liste wahrscheinlich nicht aus.
Der Wendepunkt
Diese Erkenntnis führte zu einer neuen Frage:
Wenn MCP allein nicht die beste Antwort für Agenten-Aktivierung ist, was dann?
Wir haben MCP nicht verworfen. Standardisierte Verbindungen sind für das Ökosystem wertvoll.
Aber für unsere Anforderungen brauchten wir zusätzlich etwas, das:
- Workflows ausdrückt, nicht nur Tools
- Agenten durch Sequenzen führt
- vor Schreiboperationen validiert
- Qualitätssicherungen erzwingt
- Komplexität aus dem Modellkontext in das Engineering-System verschiebt
Die Antwort war: CLI + SKILL.
Im nächsten Beitrag, Warum wir eine brandneue Apidog CLI entwickelt haben, geht es um diesen architektonischen Wechsel: weg von einer Tool-Wand, hin zu ausführbaren, geführten Prozessen für Agenten.
Wichtige Erkenntnisse
- MCP beantwortet die Frage: „Wie verbinden sich Agenten mit Tools?“
- Wir bauten 126 MCP-Tools, weil wir annahmen: mehr Tools = bessere Aktivierung.
- Reale Aufgaben zeigten vier strukturelle Probleme: Entdeckungskosten, Kontextlast, Sitzungsaufwand und Produktsemantik.
- Die Ursache: MCP verbindet Tools, aber komplexe Aufgaben benötigen ausführbare Prozesse.
- Mehr Tools sind kein Vorteil, wenn ihre Beschreibungen den Kontext füllen und der Agent Workflows erraten muss.
Laden Sie Apidog herunter, um APIs in einem Arbeitsbereich zu entwerfen, zu mocken, zu testen und zu dokumentieren. Erfahren Sie mehr über Apidog CLI für Befehlszeilen-API-Tests, CI-Automatisierung und KI-Agenten-Workflows.
Top comments (0)