---
url: https://docs.ogmabox.com/de/mcp-setup.md
description: >-
  Verbinde KI-Agenten über Streamable HTTP oder stdio mit Ogma, konfiguriere
  Berechtigungen und nutze die lokalen Endpunkte zur MCP-Verwaltung.
---

# Einrichtung des Ogma-MCP-Servers {#ogma-mcp-server-setup}

Der Ogma-MCP-Server (`ogma-mcp`) ermöglicht kompatiblen KI-Assistenten, den Projektkontext zu untersuchen und, sofern freigeschaltet, den integrierten Browser zu steuern, Anfragen zu senden, Workflows auszuführen und Nachweise zu sammeln. Seine Notiz- und Aufgaben-Tools dienen als temporärer Notizblock im Arbeitsspeicher einer MCP-Sitzung und sind von der persistenten Notizseite der Anwendung getrennt.

MCP ist für externe Tools wie Codex, Claude Code, Cursor und andere Model-Context-Protocol-Clients gedacht. Es handelt sich um eine andere Funktion als den in der Anwendung integrierten KI-Assistenten im Arbeitsbereich.

Die vollständige Ressourcen- und Tool-Liste findest du unter [MCP-Ressourcen und -Tools](./reference/mcp-tools.md).

## Schnellstart: Desktop-Anwendung {#quick-start-desktop-app}

1. Starte Ogma und öffne das Projekt, das der Agent untersuchen soll.
2. Öffne **Einstellungen > MCP**, wähle die benötigten Berechtigungen und speichere sie. Für Browserinteraktionen ist **Mit Replay senden** erforderlich.
3. Klicke auf **Starten** und kopiere den angezeigten Endpunkt, normalerweise `http://127.0.0.1:3000/mcp`.
4. Füge ihn deinem MCP-Client als **Streamable-HTTP**-Server hinzu.
5. Bitte den Agenten, `ogma_explain_capabilities` aufzurufen und `ogma://project/current` zu lesen, um die Verbindung und das aktive Projekt zu überprüfen.

Hierfür muss keine separate Binärdatei kompiliert werden. Hinweise zu Seitennavigation, Formularen, Anmeldeabläufen und Problemlösung findest du unter [Browser-Automatisierung mit MCP](./guide/mcp-browser.md).

### Verbindungsadressen {#connection-addresses}

| Schnittstelle | Standardadresse | Zweck |
| --- | --- | --- |
| MCP-Transport | `http://127.0.0.1:3000/mcp` | Hier verbinden sich native MCP-Clients. |
| Backend-REST-API | `http://127.0.0.1:8181` | Für `--api-url` beim eigenständigen MCP-Server sowie die unten beschriebenen Verwaltungs- und Bridge-Routen. |
| Proxy-Listener | `127.0.0.1:8080` | Zeichnet Browserdatenverkehr auf; dies ist kein MCP-Endpunkt. |

Desktop-Instanzen können den Backend-API-Port dynamisch vergeben. Verwende für stdio-/REST-Integrationen die tatsächliche Adresse der laufenden Instanz und für natives MCP den in den Einstellungen angezeigten Endpunkt. Ein Cloud-Chatdienst kann deine Loopback-Adresse ohne lokalen Client oder Connector nicht erreichen.

Der HTTP-Endpunkt ist zustandsbehaftet: Überlasse Initialisierung und Sitzungsheader dem Client. Es gibt keinen separaten älteren `/sse`-Endpunkt. Eigene Clients sollten der MCP-[Transportspezifikation](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) folgen.

## Wann MCP sinnvoll ist {#when-to-use-mcp}

Nutze MCP, wenn ein externer Assistent dich bei Folgendem unterstützen soll:

* Aufgezeichneten Datenverkehr zusammenfassen.
* Befunde priorisieren.
* Auf Nachweisen basierende Berichtstexte entwerfen.
* Workflows und Replay-Sitzungen prüfen.
* Auf einen festgelegten Scope begrenzte Aktionen vorbereiten, die du ausdrücklich genehmigst.

Nutze stattdessen [KI im Arbeitsbereich](./guide/workspace-ai.md), wenn du das integrierte Assistentenfenster innerhalb von Ogma verwenden möchtest.

## Voraussetzungen für den eigenständigen Betrieb {#standalone-requirements}

Nutze stdio, wenn dein Client ein lokales Programm starten muss, anstatt sich mit dem integrierten HTTP-Endpunkt zu verbinden.

* Laufendes Ogma-Backend unter seiner tatsächlichen API-Adresse (CLI-Standard: `http://127.0.0.1:8181`)
* Die Binärdatei `ogma-mcp` (aus dem Quellcode kompiliert)

## Kompilieren {#build}

```bash
cargo build --locked --bin ogma-mcp --release
```

Die Ausgabe liegt standardmäßig unter `target/release/ogma-mcp` (`ogma-mcp.exe` unter Windows), sofern du das Cargo-Zielverzeichnis nicht angepasst hast.

## Ausführen {#run}

```bash
# Connect to Ogma running on the default port
./ogma-mcp

# Connect to a custom address
./ogma-mcp --api-url http://127.0.0.1:9090

# Use a larger body preview
./ogma-mcp --body-preview-bytes 2048
```

Der Server beendet sich, wenn er die Ogma-API nicht erreichen kann. Konfiguriere den MCP-Client so, dass er diesen Befehl startet; stdout überträgt MCP-Nachrichten, stderr Diagnosemeldungen. Berechtigungen für stdio werden durch dessen eigene Flags festgelegt, nicht durch die Einstellungen des integrierten MCP-Servers.

## Tool-Ermittlung {#tool-discovery}

Der aktuelle Server bietet stets seinen vollständigen Tool-Katalog an. In den Einstellungen gibt es keine Auswahl für Tool-Profile. Ältere Werte für `--tool-profile`, `--mcp-tool-profile` und `OGMA_MCP_TOOL_PROFILE` werden aus Kompatibilitätsgründen akzeptiert, blenden jedoch weder Tools aus noch gewähren sie Berechtigungen.

Beginne bei einem großen Katalog mit `ogma_explain_capabilities` und `ogma_find_tools`, anstatt Eingaben zu erraten. Suche nach aufgabenbezogenen Stichwörtern, um geeignete Tools einzugrenzen, und frage dann einen exakten Tool-Namen ab, um seine Schnittstellendefinition zu prüfen. Die Browser- und Such-Dispatcher bieten praktische Einstiegspunkte; dedizierte Tools bleiben direkt verfügbar. Siehe [Tool-Ermittlung und Aufrufweiterleitung](./reference/mcp-tools.md#tool-discovery-and-dispatch).

## MCP-Einstellungen in der Anwendung {#in-app-mcp-settings}

Paketierte Ogma-Versionen können MCP unter **Einstellungen > MCP** verwalten. Verwende diese Einstellungsseite, wenn Ogma den integrierten MCP-Prozess für die aktive Instanz starten oder stoppen soll.

Verwende die eigenständige Binärdatei `ogma-mcp`, wenn dein KI-Client den MCP-Server direkt starten soll.

Beim Speichern der Einstellungen wird ein laufender integrierter MCP-Prozess automatisch neu gestartet. Verbinde die Clients anschließend erneut; alte Sitzungs-IDs und Bestätigungstoken können nicht wiederverwendet werden. **Laufzeitdiagnose** zeigt die jüngsten Prozessausgaben an.

Ogma bietet die MCP-Verwaltung auch über seine lokale REST-API an. Diese Routen liegen auf dem **Backend-API-Port**, nicht auf dem dedizierten MCP-Port. Sie werden von der Einstellungsseite und der KI-Bridge innerhalb der Anwendung verwendet:

| Endpunkt | Zweck |
| --- | --- |
| `GET /mcp/status` | Gibt `{ running, pid, endpoint, config, diagnostics }` zurück. `endpoint` ist im gestoppten Zustand null; die Diagnose enthält die jüngsten Datensätze mit `{ stream, message }`. |
| `POST /mcp/start` | Startet den integrierten MCP-Server mit den gespeicherten Einstellungen und gibt seinen Status zurück. Kein Body. Gibt einen Konflikt zurück, wenn er bereits läuft. |
| `POST /mcp/stop` | Stoppt den integrierten MCP-Kindprozess. |
| `GET /settings/mcp` | Gibt die gespeicherte MCP-Konfiguration zurück. |
| `PUT /settings/mcp` | Nimmt ein vollständiges Konfigurationsobjekt entgegen, speichert es und startet MCP neu, falls es läuft. Gibt die akzeptierte Konfiguration oder einen Fehler zurück. Nur Loopback-Bind-Hosts sind erlaubt. |
| `GET /mcp/tools` | Gibt `{ tools, config }` einschließlich des `inputSchema` jedes Tools zurück. Dieser REST-Katalog ist nicht paginiert. |
| `POST /mcp/tools/call` | Ruft ein Tool mit `{ "name": "ogma_explain_capabilities", "arguments": {} }` auf. Gibt `{ "result": "..." }` zurück; parse diesen Text als JSON-Ergebnishülle des Tools. Dies ist kein natives MCP-Ergebnis mit Bildblöcken. |

Die REST-Bridge nutzt die gespeicherten Berechtigungen, erfordert aber keinen gestarteten separaten HTTP-MCP-Kindprozess. Sie verwendet eine gemeinsame Bridge-Sitzung für das Backend und die Konfiguration. Bevorzuge natives MCP für getrennte Client-Sitzungen und Bildausgaben.

Bei Bridge-Fehlern ergibt das Parsen von `result` ein `{ "error": "..." }`, das die serialisierte Fehlerhülle enthält. Prüfe diesen Wert, statt einen erfolgreichen HTTP-Status als Erfolg des Tools zu werten.

Standardmäßig gespeicherte MCP-Konfiguration:

```json
{
  "bind_host": "127.0.0.1",
  "port": 3000,
  "allow_write_findings": false,
  "allow_export_data": false,
  "allow_read_secrets": false,
  "allow_send_requests": false,
  "allow_run_workflows": false,
  "allow_intercept_control": false,
  "tool_profile": "full"
}
```

Erlaubte Bind-Hosts sind `127.0.0.1`, `localhost` und `::1`; Ports müssen zwischen `1024` und `65535` liegen. Diese Version konfiguriert keine Authentifizierung für im Netzwerk erreichbares MCP, daher werden öffentliche Bind-Adressen abgelehnt. Die älteren Felder `allow_public_bind` und `acknowledge_write_tool_risk` setzen diese Einschränkung nicht außer Kraft.

## Claude Code {#claude-code}

Für den laufenden Desktop-Endpunkt:

```bash
claude mcp add --transport http ogma http://127.0.0.1:3000/mcp
```

Verwende den von Ogma angezeigten Endpunkt, falls er abweicht. Informationen zu Konfigurationsbereichen und stdio-Optionen findest du in der [MCP-Konfiguration von Claude Code](https://code.claude.com/docs/en/mcp). Prüfe die Verbindung mit: „Welche Projekte hat Ogma?“

## Cursor {#cursor}

Füge diesen Eintrag in die `.cursor/mcp.json` deines Projekts oder die benutzerweite `~/.cursor/mcp.json` ein:

```json
{
  "mcpServers": {
    "ogma": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

Aktiviere die Verbindung in Cursors MCP-Einstellungen. Siehe [Cursors MCP-Dokumentation](https://cursor.com/docs/mcp).

### Konfiguration eines stdio-Clients {#stdio-client-configuration}

Clients, die ein Programm starten, können diesen Servereintrag verwenden; passe den Speicherort ihrer Konfigurationsdatei bei Bedarf an:

```json
{
  "mcpServers": {
    "ogma": {
      "command": "/absolute/path/to/ogma-mcp",
      "args": ["--api-url", "http://127.0.0.1:8181"]
    }
  }
}
```

Verwende unter Windows den vollständigen Pfad des Programms und maskiere Backslashes in JSON. Einige Clients benötigen zusätzlich `"type": "stdio"`. Ergänze bei Bedarf Berechtigungsflags in `args`.

## Berechtigungen {#permissions}

Alle sechs privilegierten Funktionen sind standardmäßig deaktiviert. Lies ihre aktuellen Werte aus `ogma://mcp/permissions`. Ein aufgeführtes Tool kann die Ausführung dennoch verweigern, bis seine Funktion freigeschaltet ist. Die vollständige Tabelle der Flags und Umgebungsvariablen findest du in der [CLI-Referenz](./reference/cli.md#standalone-ogma-mcp-flags).

Browserinteraktionen, Kontextverwaltung, Projektwechsel und sämtliche Aufrufe für Authentifizierungsabläufe erfordern `--allow-send-requests`. Browserbeobachtung kann einen bereits laufenden Browser untersuchen, ohne dessen Steuerungstools zu aktivieren. `--allow-read-secrets` (oder `OGMA_MCP_ALLOW_READ_SECRETS=true`) erlaubt gesondert den Zugriff auf unmaskierte Werte von Umgebungsvariablen.

Der Server hat **keine Aktivitätskontingente pro Minute oder Sitzung**. Einzelne Tools setzen weiterhin ihre Eingabegrößen, Stapelgrößen, Scope-Prüfungen und Zeitlimits durch. Die alten Flags für Sende- und Workflow-Kontingente werden nicht mehr unterstützt.

## Schreibgeschützter Modus {#read-only-mode}

Standardmäßig ist der MCP-Server schreibgeschützt. Folgende Operationen sind nur nach ausdrücklicher Freischaltung verfügbar:

* Anfragen senden (Replay)
* Den integrierten Browser, Crawler, die Authentifizierungserfassung und Hilfsfunktionen für aktive Prüfungen steuern
* Workflows ausführen
* Befunde erstellen oder ändern
* Scope-Regeln oder Regeln von „Suchen & Ersetzen“ (Match & Replace) ändern
* Abgefangenen Datenverkehr ändern oder weiterleiten
* Daten löschen
* Auf geheime Werte von Umgebungsvariablen zugreifen
* Daten exportieren

Body-Vorschauen umfassen standardmäßig 512 Bytes. `--body-preview-bytes` passt die Vorschaugröße an und muss mindestens 1 betragen; es begrenzt nicht die Ausgabe jedes Tools. Nutze `ogma_get_http_entry_body` für einen vollständigen HTTP-Body oder eine gezielte Suche im Body und `ogma_get_ws_message` für eine vollständige WebSocket-Nachricht.

## Tools zum Schreiben von Befunden {#finding-write-tools}

Um die KI-gestützte Erstellung von Befunden zu aktivieren, starte ogma-mcp mit Schreibberechtigungen neu:

```bash
./ogma-mcp --allow-write-findings
```

Oder setze die Umgebungsvariable:

```bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp
```

### Verfügbare Schreibtools {#write-tools-available}

| Tool | Beschreibung |
|------|-------------|
| `ogma_preview_finding_from_evidence` | Zeigt einen Befundentwurf aus einem HTTP-Eintrag als Vorschau (schreibgeschützt, immer verfügbar) |
| `ogma_create_finding` | Erstellt einen Befund mit Schweregrad, Status, Tags und Nachweisverknüpfungen |
| `ogma_update_finding` | Aktualisiert einen vorhandenen Befund |
| `ogma_add_finding_tag` | Fügt einem Befund Tags hinzu, ohne vorhandene Tags zu ersetzen |
| `ogma_link_finding_evidence` | Verknüpft einen HTTP-Eintrag, Replay-Versuch, ein Automate-Ergebnis oder eine WS-Nachricht mit einem Befund |
| `ogma_delete_finding` | Löscht einen Befund |
| `ogma_export_findings_report` | Erstellt einen HTML-, Markdown- oder PDF-Bericht |

Die aktuelle Implementierung verwendet die Berechtigung zum Schreiben von Befunden auch für gemeinsame Schreibtools, etwa zum Aktualisieren von Umgebungsvariablen, Kommentieren des Verlaufs, Auswählen des Scopes und Ändern von „Suchen & Ersetzen“. Diese Aktionen findest du im [Tool-Katalog](./reference/mcp-tools.md).

### Beispiel: KI-gestützte Erstellung eines Befunds {#example-ai-assisted-finding-creation}

Mit `--allow-write-findings`:

1. „Analysiere den HTTP-Eintrag {id} auf Sicherheitsprobleme. Falls du ein tatsächliches Problem findest, dokumentiere es mit ogma\_create\_finding.“
2. Die KI ruft `ogma_get_http_entry` auf, um die Anfrage zu untersuchen
3. Wenn die Nachweise einen Befund stützen, ruft sie `ogma_create_finding` auf und verknüpft die Nachweise

### Mit alleiniger Befund-Schreibberechtigung weiterhin nicht verfügbar {#still-not-available-with-finding-writes-only}

* Senden mit Replay
* Workflow-Ausführung
* Erstellen von Exporten
* Steuerung der Intercept-Warteschlange
* Projektwechsel

## Export-Tools {#export-tools}

Um die KI-gestützte Erstellung von Exportaufträgen zu aktivieren, starte ogma-mcp mit Exportberechtigungen neu:

```bash
./ogma-mcp --allow-export-data
```

Oder setze die Umgebungsvariable:

```bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp
```

### Verfügbare Export-Tools {#export-tools-available}

| Tool | Erforderliche Berechtigung | Beschreibung |
|------|--------------------|-------------|
| `ogma_preview_export_plan` | Keine (schreibgeschützt) | Zeigt eine Vorschau der Daten, die ein Export enthalten würde |
| `ogma_list_export_jobs` | Keine (schreibgeschützt) | Listet die jüngsten Exportaufträge auf |
| `ogma_get_export_job` | Keine (schreibgeschützt) | Prüft den Status eines Exportauftrags |
| `ogma_get_export_download_info` | Keine (schreibgeschützt) | Liefert die Download-URL eines abgeschlossenen Exports |
| `ogma_create_export_job` | export\_data | Erstellt einen Exportauftrag |

### Unterstützte Exportarten und -formate {#supported-export-kinds-and-formats}

| Art | Beschreibung | Formate |
|------|-------------|---------|
| `http_history` | Alle über den Proxy geleiteten HTTP-Anfragen | json, csv, raw\_http |
| `search` | Gefilterte HTTP-Anfragen | json, csv, raw\_http |
| `findings` | Sicherheitsbefunde | json, csv |
| `automate_results` | Ergebnisse von Automate-Sitzungen | json, csv |

Hinweis: Das Format `raw_http` ist nur für die Arten `http_history` und `search` gültig.

### Sicherheitshinweis {#security-warning}

Exportdateien können vollständige HTTP-Anfrage- und -Antwort-Bodies enthalten, einschließlich Passwörtern, Token und personenbezogenen Daten. Gehe mit Exportdateien entsprechend sorgfältig um.

### Mit alleinigen Exportberechtigungen weiterhin nicht verfügbar {#still-not-available-with-export-permissions-only}

* Löschen von Exportdateien
* Umbenennen von Exportdateien
* Streamen von Exportinhalten über MCP
* Senden mit Replay
* Workflow-Ausführung

## Senden von Replay-Anfragen {#replay-request-sending}

Warnung: Damit wird das Senden tatsächlichen ausgehenden HTTP-Datenverkehrs über Ogma Replay aktiviert.

Zum Aktivieren:

```bash
./ogma-mcp --allow-send-requests
```

Oder über Umgebungsvariablen:

```bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp
```

### Voraussetzungen {#prerequisites}

1. Der Ogma-Proxy muss laufen
2. Für abgesicherte Replay-Sendevorgänge muss unter **Testumfänge** ein aktiver Scope konfiguriert sein
3. Der Zielhost muss im aktiven Scope liegen

### Sendetools {#send-tools}

| Tool | Berechtigung | Beschreibung |
|------|-----------|-------------|
| `ogma_preview_replay_send` | send\_requests | Bereitet einen Sendevorgang vor und liefert einen Bestätigungstoken |
| `ogma_send_replay_request` | send\_requests | Führt den Sendevorgang mit einem Bestätigungstoken aus |
| `ogma_create_replay_session_from_history` | send\_requests | Erstellt eine Replay-Sitzung |
| `ogma_create_replay_session_raw` | send\_requests | Erstellt eine Replay-Sitzung aus einer rohen Anfragedefinition |
| `ogma_browser_form_to_replay` | send\_requests | Erstellt eine Replay-Sitzung aus einem Formular auf der aktuellen Seite |
| `ogma_create_scope_preset` | send\_requests | Speichert eine Scope-Vorlage; separat mit `ogma_set_active_scope` aktivieren |
| `ogma_repeat_request` | send\_requests | Wiederholt eine aufgezeichnete Anfrage mit optionalen Änderungen |
| `ogma_replay_with_modifications` | send\_requests | Wiederholt eine aufgezeichnete Anfrage mit Überschreibungen auf Feldebene |
| `ogma_http_request` | send\_requests | Sendet eine direkte HTTP-Anfrage |
| `ogma_fetch_url` | send\_requests | Ruft eine URL ab und liefert Status, Header und Vorschau |
| `ogma_follow_redirect` | send\_requests | Folgt einer Weiterleitungskette und meldet jeden Zwischenschritt |
| `ogma_bulk_send_requests` | send\_requests | Sendet einen begrenzten Stapel von Anfragen |
| `ogma_fuzz_parameter` | send\_requests | Ersetzt einen `{{FUZZ}}`-Platzhalter durch Werte aus einer Wortliste |
| `ogma_multipart_upload` | send\_requests | Sendet Multipart-Form-Data-Anfragen zum Testen von Uploads |
| `ogma_websocket_connect` | send\_requests | Verbindet sich mit einer WebSocket-URL und tauscht Nachrichten aus |
| `ogma_login_replay_auto` | send\_requests | Sendet ein Browser-Anmeldeformular ab und erfasst ein Authentifizierungsprofil |
| `ogma_auth_capture_profile` | send\_requests | Erfasst Browser-Cookies, Speicher, Authentifizierungstoken und CSRF-Kandidaten |
| `ogma_auth_apply_profile` | send\_requests | Wendet ein erfasstes Authentifizierungsprofil auf den Browser an |
| `ogma_auth_refresh_csrf` | send\_requests | Aktualisiert CSRF-Kandidaten aus dem Browserzustand |
| `ogma_authz_matrix_test` | send\_requests | Wiederholt eine Anfrage mit mehreren Authentifizierungsprofilen |
| `ogma_run_active_probe_workflow` | send\_requests | Führt begrenzte, schwachstellenspezifische aktive Prüfungen aus |
| `ogma_test_race` | send\_requests | Sendet eine Anfrage gleichzeitig mehrfach und meldet Antworten, die vom häufigsten Status abweichen |
| `ogma_test_smuggling` | send\_requests | Sendet CL.TE- und TE.CL-Prüfanfragen zur Request-Desynchronisierung über rohes TCP |
| `ogma_test_hpp` | send\_requests | Sendet Varianten zur Prüfung auf HTTP Parameter Pollution |
| `ogma_run_nuclei` | send\_requests | Führt eine mitgelieferte oder bereitgestellte Vorlage des Vorlagenscanners gegen eine Ziel-URL aus |
| `ogma_browser_navigate` und Tools für Browserinteraktionen | send\_requests | Steuern den integrierten Browser und zeichnen den daraus entstehenden Datenverkehr auf |
| `ogma_crawl_site` | send\_requests | Durchsucht ein Ziel innerhalb des Scopes über den integrierten Browser |
| `ogma_get_replay_session` | Keine | Zeigt Metadaten einer Replay-Sitzung |
| `ogma_get_replay_attempt` | Keine | Zeigt Metadaten eines Replay-Versuchs |
| `ogma_list_replay_sessions` | Keine | Listet Replay-Sitzungen auf |

### Ablauf in zwei Schritten {#two-step-workflow}

Das bestätigungsbasierte Replay-Tool-Paar verwendet zwei Aufrufe:

1. `ogma_preview_replay_send` – Anfrage prüfen und einen Bestätigungstoken erhalten
2. `ogma_send_replay_request` – Mit dem Token bestätigen und senden

Bestätigungstoken laufen nach 5 Minuten ab, sind nur einmal verwendbar und gehören der MCP-Sitzung, in der sie erstellt wurden. Erzeuge nach Änderungen an der Anfrage oder einem MCP-Neustart erneut eine Vorschau. Diese Zwei-Schritt-Regel gilt nicht für jedes Sendetool: Direkte HTTP-Tools, Wiederholungshelfer und Browseraktionen können nach Freischaltung sofort senden.

### Beispielsitzung {#example-session}

```
Benutzer: Sende den HTTP-Eintrag abc123 erneut und prüfe die Antwort
KI: (ruft ogma_preview_replay_send mit http_entry_id="abc123" auf)
    - zeigt Anfragevorschau, Bestätigungstoken und Scope-Status --
KI: (ruft ogma_send_replay_request mit confirmation_token und request_hash auf)
    - zeigt Antwortstatus, Zeitmessung und Antwortvorschau --
```

### Mit alleinigen Berechtigungen zum Senden von Anfragen weiterhin nicht verfügbar {#still-not-available-with-request-sending-permissions-only}

* Workflow-Ausführung
* Erstellen oder Aktualisieren von Befunden
* Löschen

Halte den aktiven Scope eng begrenzt, bevor du diese Tools aktivierst. Scope-Prüfungen gelten für abgesicherte Sendepfade; betrachte den Scope nicht als universelle Firewall für beliebiges Browser-JavaScript oder jeden Helfer zum direkten Abrufen.

## Abfangen steuern {#intercept-control}

Warnung: Die Steuerung der Funktion „Abfangen“ (Intercept) ermöglicht einem MCP-Client, den aktuell in Ogmas Intercept-Warteschlange angehaltenen Live-Datenverkehr weiterzuleiten, zu verwerfen oder zu ändern.

Zum Aktivieren:

```bash
./ogma-mcp --allow-intercept-control
```

Oder über die Umgebungsvariable:

```bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp
```

### Tools für „Abfangen“ {#intercept-tools}

| Tool | Berechtigung | Beschreibung |
|------|-----------|-------------|
| `ogma_get_intercept_status` | intercept\_control | Liest den Intercept-Zustand für Anfragen, Antworten und WebSockets |
| `ogma_set_intercept_enabled` | intercept\_control | Aktiviert oder deaktiviert Intercept-Modi |
| `ogma_list_intercept_queue` | intercept\_control | Listet aktuell angehaltene Elemente auf |
| `ogma_get_intercept_item` | intercept\_control | Untersucht ein Element in der Warteschlange |
| `ogma_forward_intercept_item` | intercept\_control | Leitet ein Element aus der Warteschlange weiter, optional mit Änderungen |
| `ogma_drop_intercept_item` | intercept\_control | Verwirft ein Element aus der Warteschlange |
| `ogma_intercept_and_modify` | intercept\_control | Wartet auf ein passendes Element, ändert es und leitet es weiter |

## Workflow-Ausführung {#workflow-execution}

Warnung: Bei der Workflow-Ausführung wird Workflow-Logik ausgeführt. Manche Workflows senden HTTP-Datenverkehr oder erstellen Befunde.

Zum Aktivieren:

```bash
./ogma-mcp --allow-run-workflows
```

### Tools zur Workflow-Ausführung {#workflow-execution-tools}

| Tool | Berechtigung | Beschreibung |
|------|-----------|-------------|
| `ogma_get_workflow_safety` | Keine (schreibgeschützt) | Klassifiziert die Seiteneffekte eines Workflows |
| `ogma_preview_workflow_run` | run\_workflows | Zeigt eine Vorschau und liefert einen Bestätigungstoken |
| `ogma_run_workflow` | run\_workflows | Führt den Workflow mit einem Bestätigungstoken aus |
| `ogma_cancel_workflow_run` | run\_workflows | Bricht einen laufenden aktiven Workflow ab |

Erzeuge die Vorschau mit `workflow_id` sowie `input` für einen Konvertierungsworkflow oder `trigger_entry_id` für eine aufgezeichnete Eingabe eines aktiven Workflows. Führe den Workflow mit dem zurückgegebenen `confirmation_token` und `definition_hash` aus; Konvertierungsworkflows benötigen außerdem `input_hash` und dieselbe Eingabe `input`. Token laufen nach fünf Minuten ab und sind nur einmal verwendbar. Lies den resultierenden Lauf mit `ogma_get_workflow_run`.

Die Ausführung von Automate ist über dessen Sitzungs- und Lauf-Tools mit der **Berechtigung zum Senden von Anfragen** verfügbar, nicht mit der Berechtigung zur Workflow-Ausführung. Zum Auflisten und Untersuchen vorhandener Läufe ist keine Sendeberechtigung erforderlich.

### Zusätzliche Berechtigungsanforderungen {#cross-permission-requirements}

Workflows, die `sdk.requests.send` verwenden, benötigen zusätzlich `--allow-send-requests`.
Workflows, die `sdk.findings.create` verwenden, benötigen zusätzlich `--allow-write-findings`.

Die Erkennung basiert auf statischer Textanalyse – siehe den folgenden Hinweis.

### Hinweis zur Sicherheitsklassifizierung {#safety-classification-advisory-note}

Die Sicherheitsklassifizierung von Workflows untersucht den JavaScript-Quelltext auf Muster wie `sdk.requests.send`. Diese Erkennung ist nicht vollständig – verschleierte oder dynamisch zusammengesetzte SDK-Methodenaufrufe werden möglicherweise nicht erkannt. Prüfe immer den JavaScript-Quelltext, bevor du nicht vertrauenswürdige Workflows ausführst.

### Mit alleinigen Workflow-Berechtigungen weiterhin nicht verfügbar {#still-not-available-with-workflow-permissions-only}

* Manuelles Auslösen passiver Workflows
* Löschen
* Ändern von Umgebungsvariablen

## Beispielanfragen {#example-prompts}

Nach dem Verbinden:

* „Zeige mir die letzten 20 HTTP-Anfragen an example.com“
* „Gibt es in diesem Projekt Befunde mit hohem oder kritischem Schweregrad?“
* „Welche Workflows sind aktuell aktiviert?“
* „Prüfe, ob die HTTPQL-Abfrage `req.method.eq:\"POST\"` gültig ist“
* „Fasse den Sicherheitszustand des aktuellen Projekts zusammen“
* „Analysiere den HTTP-Eintrag {id} auf Sicherheitsprobleme“

## Problemlösung {#troubleshooting}

**Verbindung abgelehnt:** Starte zuerst Ogma (`ogma --data-dir ./ogma-data`).

**Der MCP-Client zeigt keine Tools:** Prüfe die Transport-URL oder den Programmpfad. Clients müssen allen `tools/list`-Cursorn folgen; jede Seite enthält bis zu 40 Tools. Prüfe die clientseitige Filterung und ob deine installierte Version das fehlende Tool enthält.

**Ungültige Sitzung oder ungültiger Bestätigungstoken:** Verbinde dich nach einem Neustart erneut und erzeuge einen neuen Vorschautoken.

**Browser nicht verfügbar oder Aktion fehlgeschlagen:** Lass die Desktop-Anwendung laufen. Prüfe `ogma_browser_health`, Dialoge und die [Browserwiederherstellung](./guide/mcp-browser.md#recover-from-errors). Ein Headless-Backend allein stellt die Desktop-Browser-Bridge nicht bereit.

**Screenshot enthält keinen lesbaren Text:** Nutze einen Client, der native MCP-Bildinhalte unterstützt, oder untersuche den semantischen Snapshot.

**Leere Ergebnisse:** Ogma muss zuerst Datenverkehr aufzeichnen. Surfe mit einem Proxy, der den Datenverkehr durch Ogma leitet.