Wie Guidas MCP-Server funktioniert

Guida enthält einen integrierten Model Context Protocol-Server. Dadurch kann eine externe KI wie Claude Code, Cursor oder ein anderer MCP-kompatibler Client den Browser bedienen. Der Server ist die Brücke zwischen “ich möchte diese Seite scrapen” als KI-Auftrag und den tatsächlichen DOM-Abfragen, Klicks und Speichervorgängen, die daraus folgen.

Dieser Beitrag erklärt Protokoll, Transport, Werkzeugregistrierung und das Sicherheitsmodell, das verhindert, dass die KI ohne Wissen und Zustimmung des Benutzers handelt.

Was MCP kurz gesagt ist

MCP ist ein JSON-RPC-Protokoll, das KI-Modelle mit externen Werkzeugen verbindet. Die KI sendet zum Beispiel “rufe Navigate mit url: https://example.com auf”; der Server führt den Aufruf aus und gibt das Ergebnis zurück. Das Modell berührt den Browser nicht direkt, sondern sieht Werkzeugnamen, Eingaben und Ausgaben.

Das Protokoll kennt drei primitive Konzepte:

• Tools - Funktionen, die die KI aufrufen kann
• Resources - Daten, die die KI lesen kann
• Prompts - wiederverwendbare Vorlagen

Guida implementiert Tools und Resources und stellt mehr als 100 Werkzeuge für Browserautomatisierung, Datenspeicher, Suche und weitere Bereiche bereit.

Transport: lokales HTTP

MCP unterstützt mehrere Transporte. Guida nutzt lokales HTTP über einen eingebetteten Kestrel-Server auf:

http://127.0.0.1:9315/

HTTP passt besser zu einer WPF-Desktopanwendung als stdio. Die Browseroberfläche, Freigaben, Task-Historie und Arbeitsbereichspanels bleiben sichtbar, während externe MCP-Clients verbinden.

Der Handshake ist MCP-standardkonform:

Client -> initialize
Server -> capabilities
Client -> tools/list
Client -> tools/call

Werkzeugregistrierung

Werkzeuge werden in der App mit Name, Beschreibung, JSON Schema für Parameter und asynchronem Handler registriert. Beispiele:

Unter der Haube delegieren die meisten Werkzeuge an dieselben Dienste, die auch die g.*-Scripting-API nutzen. MCP ist also eine Adapter-Schicht über gemeinsamen Services, nicht eine zweite Implementierung.

Drei Sicherheitsebenen

Die KI ist mächtig, aber nicht automatisch vertrauenswürdig. Guida legt drei Ebenen zwischen MCP-Aufruf und Browser.

Ebene 1: Zugelassene Domains

Bevor die KI zu einer URL navigieren darf, muss die Domain zugelassen sein. Guida unterstützt:

• Sitzung - Freigaben, die beim Schließen der App ablaufen
• Arbeitsbereich - Domains in domains.json
• Global - Domains aus den Einstellungen

Wildcard-Domains wie *.example.com erlauben Subdomains. Manuelles Browsen bleibt davon unabhängig; die Regel gilt für KI- bzw. Skriptnavigation über diese Oberfläche.

Ebene 2: Werkzeugfreigabe

Selbst auf einer zugelassenen Domain brauchen überwachte Werkzeuge eine Freigabe. Guida zeigt:

• den exakten Werkzeugnamen,
• die exakten Parameter,
• Optionen zum einmaligen Freigeben, Vertrauen für die Sitzung oder Ablehnen.

Das Approval Center zeigt echte Parameter, keine beschönigte Zusammenfassung. Wenn die KI Click mit button.delete-account ausführen will, sehen Sie genau diesen Selektor vorher.

Ebene 3: Nachverfolgungsprotokoll

Jeder Werkzeugaufruf wird in mcp-audit.db protokolliert:

• Werkzeugname und Parameter
• Ergebnis oder Fehler
• Dauer
• Zeitstempel und Sitzungs-ID

Das MCP History-Panel zeigt das Protokoll live. Die wichtige Eigenschaft: Die KI kann ihr eigenes Nachverfolgungsprotokoll nicht lesen oder löschen. Es gibt kein MCP-Werkzeug, das diese Datenbank freilegt.

Zugangsdaten-Isolation

Guida speichert API-Schlüssel, Passwörter und Tokens im Secrets-Panel, verschlüsselt mit Windows DPAPI. Normale Skripte können Werte mit g.secrets.getSecret(name) lesen. Skripte mit MCP-Herkunft können das nicht.

KI ruft ExecuteScript auf -> Skript ruft g.secrets.getSecret("api-key")
                          -> BLOCKIERT (MCP-Herkunft erkannt)

Ohne diese Grenze könnte ein prompt-injizierter Agent ein Skript ausführen, einen Schlüssel lesen, ihn in g.store schreiben und anschließend per MCP wieder auslesen. Die Herkunftsprüfung blockiert den ersten Schritt.

Eigene Werkzeuge

Neben den eingebauten Werkzeugen können Arbeitsbereiche eigene Werkzeuge in tools.json definieren. Sie erhalten Parameter per JSON Schema und können Zugangsdatenvorlagen in Headern verwenden.

{
  "tools": [
    {
      "name": "fetch-data",
      "description": "Fetch data from an internal API",
      "script": "scripts/fetch-data.js",
      "headers": {
        "Authorization": "Bearer {{API_TOKEN}}"
      }
    }
  ]
}

Der Agent sieht Name, Beschreibung und Schema. Den tatsächlichen Zugangsdatenwert sieht er nicht.

Architektur

AI Client
  |
  | MCP über lokales HTTP
  v
Guida MCP Server
  |-- Domain Filter
  |-- Approval Center
  |-- Audit Logger
  |-- Tool Handler
  |
  v
Gemeinsame Dienste
  |
  v
Browser / WebView2

Die Sicherheitslagen liegen in der MCP-Pipeline, bevor der Aufruf die gemeinsamen Browser-, Store-, Queue-, Such- und Netzwerkdienste erreicht.

Client verbinden

Für Claude Code oder einen anderen MCP-Client genügt eine Konfiguration wie:

{
  "mcpServers": {
    "guida": {
      "url": "http://127.0.0.1:9315/"
    }
  }
}

Der Client entdeckt Werkzeuge über tools/list und ruft sie anschließend auf. Guida behandelt überwachte Aufrufe über das Approval Center.

Weitere Details stehen in der MCP-Integration und in Eigene Werkzeuge.