Wir Bauen MCP-Server Falsch

Wenn die meisten Entwickler ihren ersten MCP-Server bauen, tun sie etwas Vorhersehbares: Sie nehmen ihre REST-API und wrappen jeden Endpoint als MCP-Tool. GET /users wird zu get_users. Das Mapping ist 1:1, mechanisch und falsch.

Es ist falsch, weil REST-APIs für Entwickler entworfen sind, die Dokumentation lesen und mehrere Aufrufe im Kopf verketten können. LLMs arbeiten nicht so. Sie arbeiten mit Tool-Beschreibungen, nicht mit Docs.

Wenn man blind REST auf MCP abbildet, zwingt man das LLM, das mentale Modell zu rekonstruieren, das die API-Docs einem menschlichen Entwickler gegeben hätten.

Die fundamentale Verschiebung: REST-Endpoints modellieren Ressourcen. MCP-Tools sollten Aufgaben modellieren.

Eine REST-API hat GET /users/{id}, GET /users/{id}/orders, GET /orders/{id}/items. Drei Endpoints, drei Aufrufe, drei Antworten.

Ein MCP-Server sollte ein get_user_order_summary Tool haben, das alles in einem Aufruf liefert. Das LLM fragte „Was hat dieser Benutzer bestellt?" — gib ihm die Antwort, nicht drei Puzzleteile.

Das fühlt sich falsch an für API-Puristen. Aber der Konsument ist kein Entwickler — es ist ein LLM, das mit weniger, vollständigeren Tool-Aufrufen besser performt.

In einer REST-API tragen Pfad und HTTP-Methode semantische Information. GET /users ist offensichtlich.

LLMs parsen keine URL-Muster. Sie lesen Tool-Beschreibungen. Ihre Beschreibung ist die einzige Dokumentation, die zählt. Wenn sie vage ist, wird das LLM das Tool falsch nutzen.

Schreiben Sie Beschreibungen, als würden Sie das Tool einem sehr wörtlich nehmenden Kollegen ohne Kontext erklären. Sagen Sie genau, was es tut, was es zurückgibt, wann es verwendet werden soll und wann NICHT.

Die meisten MCP-Server haben Beschreibungen, die in einem Technical-Writing-Kurs eine schlechte Note bekämen.

Ein Muster, das ich ständig sehe: ein MCP-Server mit search_documents, find_documents und query_documents. Drei Tools, die fast das Gleiche tun.

Für einen menschlichen Entwickler sind die Unterschiede offensichtlich. Für ein LLM sind es drei Tools mit ähnlichen Beschreibungen. Es rät in etwa 40% der Fälle falsch.

Tool-Überlappung ist die Hauptquelle von MCP-Zuverlässigkeitsproblemen. Die Lösung ist gnadenlose Deduplizierung. Wenn zwei Tools zusammengeführt werden können, führen Sie sie zusammen.

Weniger, leistungsfähigere Tools schlagen immer viele spezialisierte Tools.

Die Meta-Lektion ist einfach: MCP-Tools haben einen anderen Konsumenten als REST-APIs.

Testen Sie Ihre Tools mit echten LLMs. Nicht nur „führt das Tool korrekt aus?" — sondern „wählt das LLM das richtige Tool und übergibt die richtigen Parameter?"

Überwachen Sie, wie LLMs Ihre Tools in der Produktion tatsächlich nutzen. Sie werden überraschende Muster finden.

Die besten MCP-Server sind nicht die mit den meisten Tools. Es sind die, bei denen das LLM beim ersten Versuch die richtige Antwort bekommt.