Einen MCP Server für Architekturdokumentation nutzen
KI-Coding-Assistenten sind unverzichtbar geworden. Claude Code hilft bei der Refaktorisierung komplexer Systeme. Cursor beschleunigt die Feature-Entwicklung. GitHub Copilot schlägt Implementierungen vor. Aber all diese Tools teilen einen gemeinsamen blinden Fleck: Sie kennen Ihre Architektur nicht.
Wenn Sie einen KI-Assistenten bitten, "einen neuen Endpoint zum User Service hinzuzufügen", weiß er nicht, dass Ihr User Service über gRPC mit einem Auth Service kommuniziert, Daten in PostgreSQL speichert, Events an Kafka publiziert und eine bestimmte Reihe von Sicherheitsanforderungen hat, die in Ihren ADRs dokumentiert sind. Die KI rät, Sie korrigieren, und die Hälfte des Produktivitätsgewinns verpufft.
MCP Server beheben dieses Problem. Sie geben KI-Assistenten strukturierten Zugang zu Ihrer Architekturdokumentation und verwandeln Ihr Systemdesign in eine abfragbare, handlungsfähige Datenquelle. Dieser Leitfaden behandelt alles, was Sie über die Verwendung eines MCP Servers für Architekturdokumentation wissen müssen -- was MCP ist, warum es wichtig ist und wie Sie es mit Archyl einrichten.
Was ist MCP (Model Context Protocol)?
MCP -- das Model Context Protocol -- ist ein offener Standard, der von Anthropic entwickelt wurde, um KI-Assistenten mit externen Tools und Datenquellen zu verbinden. Es definiert einen strukturierten Weg für KI-Modelle, externe Fähigkeiten zu entdecken, aufzurufen und Ergebnisse von ihnen zu erhalten.
Denken Sie an MCP als universellen Adapter. Vor MCP hatte jeder KI-Assistent seine eigene proprietäre Art, sich mit externen Tools zu integrieren. MCP standardisiert dies und schafft ein einzelnes Protokoll, das über verschiedene KI-Assistenten hinweg funktioniert.
Ein MCP Server ist ein Dienst, der eine Reihe von Tools über das MCP-Protokoll bereitstellt. Jedes Tool hat einen Namen, eine Beschreibung, Eingabeparameter und ein Ausgabeformat. Wenn sich ein KI-Assistent mit einem MCP Server verbindet, entdeckt er die verfügbaren Tools und kann sie bei Bedarf während einer Konversation aufrufen.
Für Architekturdokumentation bedeutet das, dass Ihr Architekturmodell zu einer Menge abfragbarer, modifizierbarer Tools wird, die jeder MCP-kompatible KI-Assistent nutzen kann. Die KI muss keine Dateien parsen oder über Ihre Systemstruktur raten -- sie kann direkt die autoritative Quelle der Wahrheit abfragen.
Warum Architektur MCP braucht
Architekturdokumentation liegt an der Schnittstelle mehrerer Bedürfnisse, die MCP perfekt adressiert.
Kontext ist alles für KI-gestützte Entwicklung
Die Qualität von KI-generiertem Code ist direkt proportional zur Qualität des Kontexts, den die KI hat. Wenn ein KI-Assistent Ihre Architektur versteht -- welche Services existieren, wie sie kommunizieren, welche Technologien sie verwenden, welche Constraints gelten -- generiert er Code, der sich natürlich in Ihr System einfügt.
Ohne Architekturkontext macht der KI-Assistent Annahmen. Er könnte eine REST-API vorschlagen, wenn Ihr Service gRPC verwendet. Er könnte eine direkte Datenbankverbindung erstellen, wenn Ihre Architektur den Weg über eine Service-Schicht erfordert. Er könnte einen synchronen Aufruf vorschlagen, wenn Ihr System Event-Driven-Kommunikation verwendet.
MCP gibt KI-Assistenten Zugang zur realen Architektur und eliminiert diese Diskrepanzen.
Architekturdokumentation ist strukturierte Daten
Im Gegensatz zu formloser Dokumentation (Wikis, Confluence-Seiten, README-Dateien) ist Architekturdokumentation, die im C4-Framework modelliert ist, inhärent strukturiert. Systems enthalten Containers. Containers enthalten Components. Elemente haben Technologies, Descriptions und Relationships. ADRs haben Status und betroffene Elemente.
Diese Struktur bildet natürlich auf MCP-Tools ab. Jeder Typ architektonischer Elemente wird zu einer abfragbaren Entität. Jede Operation (list, get, create, update) wird zu einem Tool. Der KI-Assistent kann das Architekturmodell so navigieren, wie ein Entwickler ein Dateisystem navigiert.
Dokumentation sollte bidirektional sein
Die meisten Dokumentationstools sind aus API-Perspektive nur lesbar. Sie können Dokumente ansehen, aber ihre Änderung erfordert das Öffnen einer bestimmten Anwendung. MCP ermöglicht bidirektionale Interaktion: Der KI-Assistent kann sowohl aus dem Architekturmodell lesen als auch in es schreiben.
Das bedeutet, ein KI-Assistent kann Ihre Architektur nicht nur abfragen, sondern auch Modifikationen vorschlagen -- eine neue Komponente hinzufügen, eine Beziehung erstellen, einen ADR-Entwurf verfassen. Der Entwickler prüft und genehmigt diese Änderungen, aber die KI erledigt die mechanische Arbeit der Dokumentationsaktualisierung.
Archyls MCP Server: 56 Tools für Architektur
Archyl bietet eine der umfassendsten MCP-Server-Implementierungen für Architekturdokumentation. Mit 56 Tools, die den vollen Umfang der Architekturmodellierung abdecken, behandelt er alles von der Abfrage des C4-Modells bis zur Verwaltung von Releases und dem Tracking von Drift.
Hier ist ein Überblick über die Tool-Kategorien.
Das C4-Modell abfragen
Die zentralen Abfrage-Tools lassen den KI-Assistenten Ihre Architektur auf jeder Ebene erkunden:
- list_systems / get_project_c4_model -- Alle Software Systems in einem Projekt entdecken
- list_containers / list_components -- Die C4-Hierarchie navigieren
- list_relationships -- Verstehen, wie Elemente verbunden sind
- get_element_technologies -- Den Technologie-Stack jedes Elements sehen
- get_element_owners -- Wissen, wem was gehört
Diese Tools ermöglichen natürlichsprachliche Abfragen über Ihre Architektur. Wenn Sie fragen "Von welchen Datenbanken hängt der Order Service ab?", kann die KI die Relationships des Order Service auflisten, nach Datenbank-Containern filtern und eine präzise Antwort liefern.
Architekturelemente verwalten
Schreib-Tools lassen den KI-Assistenten das Architekturmodell modifizieren:
- create_system / update_system / delete_system -- Software Systems verwalten
- create_container / update_container / delete_container -- Containers verwalten
- create_component / update_component / delete_component -- Components verwalten
- create_relationship / update_relationship / delete_relationship -- Verbindungen verwalten
Diese Tools sind besonders leistungsfähig, um die Dokumentation während der Entwicklung aktuell zu halten. Wenn Sie einen neuen Service zu Ihrer Codebasis hinzufügen, können Sie den KI-Assistenten bitten, den entsprechenden Container zum Architekturmodell hinzuzufügen, seine Technologies zu setzen und die passenden Relationships zu erstellen -- alles ohne Ihre IDE zu verlassen.
Architecture Decision Records
ADR-Tools bringen Entscheidungsdokumentation in den KI-Workflow:
- list_adrs / get_adr -- Bestehende Entscheidungen abfragen
- create_adr / update_adr -- Neue ADRs erstellen oder bestehende aktualisieren
- link_adr_to_element -- Entscheidungen mit betroffenen Elementen verknüpfen
Wenn Sie eine Technologieentscheidung mit Ihrem KI-Assistenten diskutieren, kann er bestehende ADRs nach verwandten Entscheidungen prüfen, einen neuen ADR für die aktuelle Entscheidung entwerfen und ihn mit den relevanten architektonischen Elementen verknüpfen.
API Contracts und Event Channels
Integrationsdokumentations-Tools decken Service-Grenzen ab:
- list_api_contracts / create_api_contract -- API-Spezifikationen verwalten
- list_event_channels / create_event_channel -- Asynchrone Kommunikation modellieren
- link_api_contract / link_event_channel -- Spezifikationen mit Elementen verbinden
Diese Tools helfen, die Verbindung zwischen Architektur und Implementierung aufrechtzuerhalten. Wenn Sie einen neuen API-Endpoint erstellen, kann die KI prüfen, ob ein API Contract für diesen Service existiert und eine Aktualisierung vorschlagen.
Dokumentation und Kollaboration
Breitere Dokumentationstools unterstützen Team-Workflows:
- create_documentation / update_documentation -- Projektdokumentation verwalten
- create_comment / list_comments -- Architekturelemente annotieren
- list_flows / create_flow -- Benutzer- und System-Flows dokumentieren
- get_drift_score / compute_drift_score -- Dokumentationsgenauigkeit prüfen
Releases und Metriken
Operationelle Tools verbinden Architektur mit Delivery:
- create_release / list_releases -- Deployments verfolgen
- get_dora_metrics / get_dora_trend -- Engineering-Performance messen
- list_environments -- Deployment-Ziele verstehen
Praxisbeispiele: MCP in Aktion
Hier sind konkrete Beispiele, wie Entwickler Archyls MCP Server in ihrem täglichen Workflow nutzen.
Beispiel 1: Systems aus Claude Code abfragen
Sie arbeiten in Claude Code und müssen die Architektur verstehen, bevor Sie Änderungen vornehmen:
Sie: Welche Systems und Containers hat unser Projekt?
Claude: Lassen Sie mich Ihre Architektur prüfen.
[Ruft list_systems auf, dann list_containers für jedes System]
Ihr Projekt "E-Commerce Platform" hat 3 Systems:
1. E-Commerce Platform (software_system)
- API Gateway (Go, Kong)
- User Service (Go, PostgreSQL)
- Order Service (Java, PostgreSQL)
- Product Service (Node.js, MongoDB)
- Notification Service (Python, Redis)
- Event Bus (Kafka)
2. Stripe (external_system)
- Payment-Processing-Gateway
3. SendGrid (external_system)
- Transaktionaler E-Mail-Service
Die KI liefert echte Daten aus Ihrer dokumentierten Architektur, keine Halluzination.
Beispiel 2: Components aus Cursor erstellen
Sie fügen einem Service ein neues Modul hinzu und möchten es dokumentieren:
Sie: Ich habe gerade eine RateLimiter-Komponente zum API Gateway
hinzugefügt. Sie verwendet Redis und die
golang.org/x/time/rate-Bibliothek. Kannst du sie zu unserer
Architektur hinzufügen?
Cursor: Ich werde das zu Ihrem C4-Modell hinzufügen.
[Ruft create_component mit name="RateLimiter",
container="API Gateway", technologies=["Redis", "Go"] auf]
[Ruft create_relationship von RateLimiter
zum Redis-Container auf]
Erledigt. Ich habe die RateLimiter-Komponente zum API Gateway
hinzugefügt und eine Beziehung zu Ihrem Redis-Container erstellt.
Die Dokumentation wird in Sekunden aktualisiert, ohne die IDE zu verlassen.
Beispiel 3: Drift vor einem Refactoring prüfen
Vor einer größeren Refaktorisierung möchten Sie wissen, wie akkurat die Dokumentation ist:
Sie: Was ist unser aktueller Drift Score? Gibt es
undokumentierte Services?
Claude: Lassen Sie mich das prüfen.
[Ruft get_drift_score auf]
[Ruft get_drift_details auf]
Ihr Drift Score ist 78/100 (Gut).
Erkannte Probleme:
- Der Search Service läuft in Produktion, ist aber nicht
in Ihrem C4-Modell dokumentiert
- Der Analytics Service hat 2 undokumentierte Beziehungen
zum Data Warehouse
- In der Technologieliste des API Gateways fehlt "Redis"
(kürzlich für Rate Limiting hinzugefügt)
Soll ich diese Probleme beheben?
Die KI identifiziert genau, was veraltet ist, und kann es automatisch korrigieren.
Beispiel 4: Einen ADR entwerfen
Während einer Design-Diskussion über den Wechsel von REST zu gRPC für interne Service-Kommunikation:
Sie: Wir erwägen, die interne Service-Kommunikation von REST
auf gRPC umzustellen. Kannst du einen ADR entwerfen und
prüfen, ob wir bestehende Entscheidungen dazu haben?
Claude: Lassen Sie mich zuerst bestehende ADRs prüfen.
[Ruft list_adrs auf]
Ich habe einen verwandten ADR gefunden:
- ADR-007: "REST für alle internen APIs verwenden"
(Status: Accepted)
Dies wurde vor 18 Monaten entschieden.
Ich werde einen neuen ADR entwerfen, der ihn ersetzt.
[Ruft create_adr mit title="Interne Kommunikation
von REST auf gRPC migrieren" auf]
ADR-015 erstellt mit:
- Kontext: Aktuelle REST-basierte Kommunikation verursacht
Serialisierungs-Overhead...
- Entscheidung: gRPC mit Protocol Buffers für alle
neue interne Service-Kommunikation einführen...
- Status: Proposed
- Ersetzt: ADR-007
Soll ich diesen mit den betroffenen Services verknüpfen?
Die KI prüft auf verwandte Entscheidungen, entwirft einen neuen ADR und bietet an, ihn mit den relevanten Architekturelementen zu verknüpfen.
Beispiel 5: Auswirkungen vor Änderungen verstehen
Bevor Sie einen Service modifizieren, möchten Sie den Blast Radius verstehen:
Sie: Ich muss das Datenbankschema des Order Service ändern.
Was hängt sonst noch vom Order Service ab?
Claude: Lassen Sie mich die Abhängigkeiten nachverfolgen.
[Ruft list_relationships gefiltert nach Order Service auf]
[Ruft get_element_owners für abhängige Elemente auf]
Der Order Service hat diese Abhängigen:
- API Gateway -> Order Service (REST, Bestellverwaltung)
- Order Service -> Payment Service (gRPC, Zahlungsverarbeitung)
- Order Service -> Event Bus (publiziert OrderCreated,
OrderUpdated, OrderCancelled Events)
- Notification Service konsumiert Order Events vom Event Bus
- Analytics Service konsumiert Order Events vom Event Bus
Zuständig:
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team
Schema-Änderungen könnten den Payment Service (direkte
Abhängigkeit) und jeden Consumer von Order Events betreffen.
Ich empfehle eine Abstimmung mit dem Payments Team und dem
Data Team.
Archyls MCP Server einrichten
Der Einstieg mit Archyls MCP Server dauert nur wenige Minuten. So richten Sie ihn für die gängigsten KI-Assistenten ein.
Einrichtung für Claude Code
Fügen Sie den Archyl MCP Server zu Ihrer Claude-Code-Konfiguration hinzu:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Nach der Konfiguration entdeckt Claude Code automatisch alle 56 Tools und kann sie in jeder Konversation verwenden.
Einrichtung für Cursor
Cursor unterstützt MCP Server über seine Einstellungen. Fügen Sie Archyl unter dem MCP-Bereich hinzu:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Nach dem Hinzufügen der Konfiguration starten Sie Cursor neu. Die Archyl-Tools erscheinen in der MCP-Tools-Liste, und Cursor kann sie während der Code-Generierung und beim Refactoring verwenden.
Einrichtung für andere MCP-kompatible Tools
Jedes Tool, das das MCP-Protokoll unterstützt, kann sich mit Archyls MCP Server verbinden. Der Server stellt einen Standard-MCP-Endpoint mit Tool-Discovery bereit, sodass kompatible Clients die verfügbaren Tools automatisch erkennen und auflisten.
API-Key-Generierung
Generieren Sie Ihren MCP-API-Key aus dem Archyl-Dashboard:
- Navigieren Sie zu Ihren Organisationseinstellungen
- Gehen Sie zum API-Bereich
- Erstellen Sie einen neuen API-Key mit den entsprechenden Berechtigungen
- Kopieren Sie den Key in Ihre MCP-Server-Konfiguration
Wir empfehlen, separate API-Keys für verschiedene Anwendungsfälle zu erstellen (z. B. einen für Claude Code, einen für CI/CD), damit Sie sie unabhängig rotieren können.
Best Practices für MCP-gestützte Architekturdokumentation
Mit Read-Only beginnen
Wenn Sie den MCP Server erstmals einrichten, beginnen Sie mit reinen Leseabfragen. Werden Sie vertraut mit der Fähigkeit des KI-Assistenten, Ihre Architektur zu erkunden, bevor Sie Schreiboperationen aktivieren. Das baut Vertrauen in die Genauigkeit und Zuverlässigkeit des Tools auf.
KI-generierte Änderungen überprüfen
Wenn der KI-Assistent Architekturelemente erstellt oder modifiziert, prüfen Sie die Änderungen, bevor Sie sie als endgültig betrachten. Archyls Historie- und Versions-Features lassen Sie sehen, was sich geändert hat, und bei Bedarf rückgängig machen. Die KI ist ein leistungsstarker Assistent, aber architektonische Entscheidungen sollten immer menschliche Aufsicht haben.
MCP mit Architecture as Code kombinieren
MCP und Architecture as Code sind komplementär. Nutzen Sie MCP für interaktive Abfragen und schnelle Updates während der Entwicklung. Nutzen Sie Architecture as Code (die archyl.yaml-Datei) für autoritative, versionskontrollierte Definitionen, die durch Code Review gehen. Die beiden Ansätze verstärken sich gegenseitig.
MCP in Code Reviews nutzen
Während Code Reviews bitten Sie den KI-Assistenten zu prüfen, ob die Code-Änderungen mit der dokumentierten Architektur übereinstimmen. "Passt dieser neue API-Endpoint zum dokumentierten API Contract für diesen Service?" oder "Gehen diese Datenbankabfragen über die Service-Schicht, wie dokumentiert?" Die KI kann Code in Echtzeit gegen das Architekturmodell validieren.
Ihr Team über die verfügbaren Tools informieren
Die größte Hürde für MCP-Adoption ist Bewusstsein. Die meisten Entwickler wissen nicht, welche Fragen die KI über ihre Architektur beantworten kann. Teilen Sie Beispiele, erstellen Sie einen Spickzettel mit nützlichen Abfragen und demonstrieren Sie MCP-Workflows in Team-Meetings.
Die Zukunft KI-gestützter Architekturdokumentation
MCP Server stellen einen fundamentalen Wandel dar, wie Teams mit Architekturdokumentation interagieren. Statt dass Dokumentation ein passives Artefakt ist, das Entwickler lesen (oder häufiger nicht lesen), wird sie zu einem aktiven Teilnehmer im Entwicklungsworkflow.
Wenn Ihr KI-Assistent die Architektur vor der Code-Generierung abfragen, Conformance nach Änderungen prüfen und Dokumentation aktualisieren kann, während sich das System weiterentwickelt, verschwindet die Barriere zwischen "am System arbeiten" und "das System dokumentieren".
Architekturdokumentation hört auf, etwas zu sein, das Sie separat pflegen, und wird zu etwas, das in jede Entwicklungsinteraktion eingewoben ist. Jede Frage, die Sie der KI stellen, jede Code-Änderung, die Sie vornehmen, jede Design-Diskussion, die Sie führen -- all das kann vom Architekturmodell informiert werden und sich darin widerspiegeln.
Das ist die Zukunft, die Archyl aufbaut. Der MCP Server ist die Brücke zwischen KI-gestützter Entwicklung und strukturierter Architekturdokumentation. Und mit 56 Tools, die den vollen Umfang der Architekturmodellierung abdecken, ist er umfassend genug, um jeden Workflow zu unterstützen, den Ihr Team benötigt.
Starten Sie mit Archyls MCP Server und geben Sie Ihrem KI-Assistenten den Architekturkontext, der ihm bisher gefehlt hat.