MCP-Server

Archyl bietet einen Model Context Protocol (MCP) Server, der KI-Assistenten ermöglicht, mit Ihrer Architekturdokumentation zu interagieren. Dies ermöglicht leistungsstarke KI-gestützte Architekturerkundung und -dokumentation.

Was ist MCP?

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das KI-Assistenten sicheren Zugriff auf externe Tools und Datenquellen ermöglicht. Mit dem MCP-Server von Archyl kann Ihr KI-Assistent:

• Ihre Projekte und deren vollständiges C4-Modell durchsuchen und abfragen
• Architekturelemente, Beziehungen und Diagramme erstellen und ändern
• ADRs, Dokumentation, API-Contracts und Event-Kanäle lesen und schreiben
• Konformitätsregeln, Drift-Scores, DORA-Metriken und Ownership prüfen, bevor er Code schreibt
• Releases, Change Requests, Kommentare und Historie nachverfolgen

Unterstützte Clients

Der MCP-Server von Archyl funktioniert mit:

• Antigravity - Die KI-gestützte IDE von Google
• Claude Code - Das CLI-Tool von Anthropic
• Claude Desktop - Die Desktop-Anwendung von Claude
• Cursor - KI-orientierter Code-Editor
• OpenAI Codex - Der KI-Coding-Assistent von OpenAI
• VS Code - Mit GitHub Copilot Chat
• Warp - Modernes Terminal mit KI-Integration
• Windsurf - Die KI-gestützte IDE von Codeium

Authentifizierung

API-Schlüssel (empfohlen)

Die meisten Clients authentifizieren sich mit einem API-Schlüssel. Je nach verwendetem Tool:

• Tools mit Header-Unterstützung (Claude Code, Cursor, Warp, Windsurf, Antigravity): Verwenden Sie den X-API-Key Header
• Tools ohne Header-Unterstützung (Claude Desktop, VS Code, OpenAI Codex): Verwenden Sie den ?apiKey=IHR_API_SCHLUESSEL URL-Parameter

Generieren Sie einen API-Schlüssel auf Ihrer Profil → API-Schlüssel-Seite.

Die Scopes des Schlüssels bestimmen, was der Assistent tun darf: Ein schreibgeschützter Schlüssel kann jedes list_*- und get_*-Tool aufrufen, während create_*, update_*, delete_* und import_dsl einen Schlüssel mit Schreib-Scope erfordern. Ihrem Agenten einen schreibgeschützten Schlüssel zu geben, ist der einfachste Weg, ihn Ihre Architektur erkunden zu lassen, ohne dass er sie verändern kann.

OAuth 2.1

Der Server implementiert außerdem OAuth 2.1 mit dynamischer Client-Registrierung — für Clients, die sich über eine Browser-Anmeldung verbinden statt über einen eingefügten Schlüssel (die Scopes mcp:read und mcp:write entsprechen den oben beschriebenen API-Schlüssel-Scopes). Richten Sie einen solchen Client auf denselben Endpunkt aus, und er erkennt den Ablauf automatisch über:

https://api.archyl.com/.well-known/oauth-authorization-server
https://api.archyl.com/.well-known/oauth-protected-resource

Einrichtung

Antigravity

1. Öffnen Sie Antigravity und klicken Sie auf das "..." Menü im Agent-Panel
2. Wählen Sie "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. Fügen Sie zu ~/.gemini/antigravity/mcp_config.json hinzu:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "IHR_API_SCHLUESSEL"
      }
    }
  }
}

4. Starten Sie Antigravity neu, um die Änderungen anzuwenden

Hinweis: Antigravity verwendet serverUrl anstelle von url für HTTP-basierte MCP-Server.

Claude Code

Erstellen Sie eine .mcp.json-Datei im Projektstamm:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "IHR_API_SCHLUESSEL"
      }
    }
  }
}

Führen Sie Claude Code aus - es erkennt den MCP-Server automatisch.

Claude Desktop

1. Öffnen Sie die Claude Desktop-Einstellungen
2. Navigieren Sie zu Entwickler → MCP-Server
3. Klicken Sie auf "Server hinzufügen" und fügen Sie hinzu:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=IHR_API_SCHLUESSEL"
    }
  }
}

4. Starten Sie Claude Desktop neu

Hinweis: Remote-Konnektoren von Claude Desktop unterstützen keine benutzerdefinierten Header, daher muss der API-Schlüssel als URL-Query-Parameter übergeben werden.

Cursor

Erstellen Sie eine .cursor/mcp.json-Datei in Ihrem Projekt:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "IHR_API_SCHLUESSEL"
      }
    }
  }
}

Starten Sie Cursor neu, um den MCP-Server zu laden.

OpenAI Codex

Öffnen oder erstellen Sie ~/.codex/config.toml und fügen Sie hinzu:

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=IHR_API_SCHLUESSEL"

Starten Sie Codex CLI oder IDE neu, um die Änderungen anzuwenden.

VS Code

1. Öffnen Sie die VS Code-Einstellungen (Cmd/Ctrl + ,)
2. Suchen Sie nach "MCP" und klicken Sie auf "In settings.json bearbeiten"
3. Fügen Sie hinzu:

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=IHR_API_SCHLUESSEL"
      }
    }
  }
}

Warp

1. Öffnen Sie Warp und gehen Sie zu Einstellungen > MCP-Server
2. Klicken Sie auf "Server hinzufügen" und fügen Sie die Konfiguration ein:

{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "IHR_API_SCHLUESSEL"
    }
  }
}

3. Starten Sie Warp neu, um die Änderungen anzuwenden

Windsurf

Öffnen Sie die MCP-Konfigurationsdatei unter ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "IHR_API_SCHLUESSEL"
      }
    }
  }
}

Starten Sie Windsurf neu, um die Änderungen anzuwenden.

Tool-Referenz

Der Server stellt 189 Tools bereit. Sie folgen einem vorhersehbaren Namensschema, sodass ein Assistent das passende meist erraten kann:

Die meisten projektbezogenen Tools erwarten eine projectId; elementbezogene Tools erwarten eine elementId sowie einen elementType (die C4-Ebene: 1 = System, 2 = Container, 3 = Komponente, 4 = Code). Bitten Sie Ihren Assistenten, zuerst list_projects aufzurufen — von dort holt er sich die benötigten IDs.

Ihr Client ermittelt diese Liste automatisch über tools/list, sie ist also immer mit dem Server synchron. Die folgenden Tabellen richten sich an Menschen, die entscheiden möchten, wonach sie fragen sollen.

Tool-Profile

189 Tools sind mehr, als ein Coding-Agent für eine begrenzte Aufgabe braucht — sie alle anzukündigen kostet Kontext. Hängen Sie ?profile=coding an die MCP-URL an (oder senden Sie den Header X-Archyl-Tool-Profile: coding), um die Oberfläche auf 16 Tools zu reduzieren: aufgabenbezogener Kontext, der Harness-Arbeitssitzungszyklus und die Konformitäts-/Diff-Prüfungen. Lassen Sie den Parameter weg (oder verwenden Sie profile=full) für den vollständigen Katalog.

Agenten-Kontext (4)

Hier anfangen: Diese Tools liefern einem Assistenten das Architekturbild in einem einzigen Aufruf statt in vielen.

Harness-Arbeitssitzungen (8)

Der kontrollierte Arbeitszyklus für Coding-Agents: eine Arbeitseinheit ankündigen, um fokussierten Kontext und beratende Sperren zu erhalten, während der Arbeit ein Lebenszeichen senden und mit einem Ergebnis abschließen, das einen Architektur-Änderungsantrag öffnen kann. Dazu Projektgedächtnis: Fakten für künftige Bearbeiter merken und abrufen, was frühere Sitzungen gelernt haben.

Projekte (7)

Organisationen & Teams (5)

C4-Elemente (15)

Systeme (Ebene 1), Container (Ebene 2), Komponenten (Ebene 3) und Code-Elemente (Ebene 4).

Beziehungen (4)

Diagramm-Layout & Overlays (5)

Dokumentation (11)

Architecture Decision Records (6)

API-Contracts (8)

OpenAPI-, gRPC-, GraphQL-, AsyncAPI- und MCP-Tool-Contracts.

Event-Kanäle (8)

Flows & Whiteboards (8)

Kommentare & Diskussionen (11)

Ownership (6)

Technologien & Radar (10)

Releases & Umgebungen (10)

Architektur-Change-Requests (6)

Konformitätsregeln (9)

Drift-Erkennung (4)

DORA-Metriken, ROI & Prognosen (4)

Historie & Zeitreise (5)

Insights (3)

Marketplace & Widgets (15)

Webhooks (7)

Organisationsweite Architektur (9)

Projektübergreifende Ansichten und Artefakte auf Organisationsebene.

Architecture as Code (1)

Beispielkonversationen

Architektur Erkunden

Sie: "Welche Systeme sind in meinem E-Commerce-Projekt?"

KI: Verwendet das list_systems-Tool "Ihr E-Commerce-Projekt hat 4 Systeme: Web-Shop, Zahlungsservice, Inventarsystem und Benachrichtigungsservice..."

Elemente Erstellen

Sie: "Füge einen neuen Container namens Redis Cache zum Web-Shop-System für Session-Speicherung hinzu"

KI: Verwendet das create_container-Tool "Ich habe den Redis Cache-Container im Web-Shop-System mit der Beschreibung 'In-Memory-Cache für Session-Speicherung' erstellt."

Dokumentation

Sie: "Erstelle einen ADR für unsere Entscheidung, PostgreSQL statt MongoDB zu verwenden"

KI: Verwendet das create_adr-Tool "Ich habe ADR-001: Datenbanktechnologie-Auswahl erstellt, das die Entscheidung für PostgreSQL wegen seiner ACID-Konformität und Abfrageflexibilität dokumentiert..."

Vor dem Schreiben von Code

Sie: "Ich bin dabei, Rate Limiting zum Checkout-Flow hinzuzufügen. Was sollte ich wissen?"

KI: Verwendet find_relevant_context und impact_of "Der Checkout berührt das API Gateway und den Orders-Service. Eine Änderung am Gateway wirkt sich auf 6 nachgelagerte Container aus. ADR-014 schreibt bereits Redis für Throttling vor, und eine Konformitätsregel verbietet neue Abhängigkeiten vom Legacy-Session-Store..."

Governance-Prüfung

Sie: "Weichen wir von der dokumentierten Architektur ab?"

KI: Verwendet get_drift_score und run_conformance_check "Der Drift-Score liegt bei 82 % (gegenüber 91 % im Vormonat). Zwei Verstöße: Der Search-Service greift direkt auf die Orders-Datenbank zu, und Payments verwendet einen nicht freigegebenen HTTP-Client..."

Endpunkt

Streamable HTTP (MCP)

https://api.archyl.com/mcp

Verwenden Sie diesen Endpunkt, um Ihren KI-Assistenten mit der Archyl-Architekturdokumentation zu verbinden. Er unterstützt das Streamable HTTP-Transportprotokoll.

Fehlerbehebung

Verbindung Fehlgeschlagen

• Prüfen Sie, ob Ihr API-Schlüssel gültig ist
• Stellen Sie sicher, dass die Endpunkt-URL korrekt ist
• Überprüfen Sie Ihre Netzwerkverbindung

Authentifizierung Fehlgeschlagen

• Für Tools mit Header-Unterstützung: Überprüfen Sie, ob der X-API-Key Header korrekt gesetzt ist
• Für Tools ohne Header-Unterstützung: Überprüfen Sie, ob der ?apiKey= Parameter in der URL enthalten ist
• Stellen Sie sicher, dass Ihr API-Schlüssel nicht abgelaufen ist

Tool Nicht Gefunden

• Stellen Sie sicher, dass Sie den korrekten Tool-Namen verwenden — siehe die Tool-Referenz, oder bitten Sie Ihren Client, seine Tool-Liste zu aktualisieren
• Manche Clients speichern tools/list zwischen; starten Sie den Client nach einem Upgrade neu

Schreib-Tools Abgelehnt

• create_*, update_*, delete_* und import_dsl benötigen einen API-Schlüssel mit Schreib-Scope — ein schreibgeschützter Schlüssel kann nur list_* und get_* aufrufen
• Prüfen Sie Ihren Abonnementplan: Manche Funktionen (Webhooks, Marketplace-Verbindungen, verwaltete Agent-Läufe) sind planabhängig

Antigravity-spezifische Probleme

• Stellen Sie sicher, dass Sie serverUrl (nicht url) für die Konfiguration verwenden
• Der Konfigurationsdatei-Speicherort ist ~/.gemini/antigravity/mcp_config.json

OpenAI Codex-spezifische Probleme

• Stellen Sie sicher, dass die TOML-Syntax in ~/.codex/config.toml korrekt ist
• Verwenden Sie [mcp_servers.archyl] als Tabellenname

Warp-spezifische Probleme

• Navigieren Sie zu Einstellungen > MCP-Server, um Konfigurationen zu verwalten
• Starten Sie Warp nach Konfigurationsänderungen neu

Best Practices

Seien Sie Spezifisch

Wenn Sie Ihre KI bitten, Architektur zu ändern, seien Sie spezifisch:

• Projektnamen einschließen
• Elementtypen angeben
• Beschreibungen bereitstellen

Änderungen Überprüfen

Überprüfen Sie immer KI-erstellte Elemente:

• Prüfen Sie, ob Namen und Beschreibungen korrekt sind
• Verifizieren Sie, dass Beziehungen stimmen
• Aktualisieren Sie bei Bedarf

Zur Erkundung Verwenden

MCP ist großartig für:

• Schnelles Erkunden großer Architekturen
• Generieren von initialer Dokumentation
• Beantworten von Fragen zu Ihren Systemen