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 auflisten und durchsuchen
• Architekturelemente erstellen und ändern
• Dokumentation generieren
• Fragen zu Ihrer Architektur beantworten

Unterstützte Tools

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

Der MCP-Server erfordert einen API-Schlüssel zur Authentifizierung. 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.

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.

Verfügbare Tools

Nach der Verbindung kann Ihr KI-Assistent diese Tools verwenden:

Projektverwaltung

Architekturelemente

Beziehungen

Dokumentation

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..."

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
• Prüfen Sie, ob Ihr API-Schlüssel die erforderlichen Berechtigungen hat

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