# Bezug auf die Werkzeuge

Der Maetra-MCP-Server zeigt ein fähigkeitsabhängiges Tool-Set. Anruf `tools/list` um die Tools zu finden, die für den aktuellen Arbeitsbereich und den API-Schlüssel verfügbar sind.

Aufrufen eines Tools mit `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<token from get_mcp_access>",
      "session_ref": "conversation_01JY8Q",
      "action": "Edit the refund approval route"
    }
  }
}
```

### Zugangsvorflug

#### get\ mcp\ access

Erforderlicher erster Aufruf für jeden neuen Benutzerwechsel oder Arbeitszyklus, nach Kontextverdichtung oder Neustart und immer dann, wenn Maetra eine Aktualisierung des Zugriffs anfordert. Keine Argumente.

Die Antwort enthält:

| Feld | Beschreibung |
| ----- | ----------- |
| `workspace` | Workspace ID, MCP aktivierter Status und Konfigurationsversion. |
| `capabilities` | Ermöglichte Zustand, Vernunft und erlaubte Werkzeuge für Secure, Govern und Task Guard. |
| `required_behavior` | Laufzeitanweisungen, die der Host befolgen muss. |
| `mcp_access_token` | Kurzlebiges Token, das von jedem Fähigkeitswerkzeug benötigt wird. |
| `expires_at` | Access-Token Ablauf. |

```json
{
  "name": "get_mcp_access",
  "arguments": {}
}
```

> **Note**
> Jedes Werkzeug unten erfordert ein zusätzliches String-Argument, `mcp_access_token`, mit dem aktuellen Token zurückgegeben von `get_mcp_access`.


### Task Guard Werkzeuge

#### start\ task

Starten oder Übergang zur aktuellen benutzerautorisierten Task Guard-Task.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `session_ref` | Schnurschnur | ✓ | Stabile Host-Konversation oder Session-Referenz. |
| `objective` | Schnurschnur | ✓ | Das aktuelle Ziel des direkten Benutzers. |
| `idempotency_key` | Schnurschnur | ✓ | Stabile Retry-Taste für den Task-Start. |
| `title` | Schnurschnur || Kurze Aufgabenbezeichnung. |
| `agent_name` / `agent_id` | Schnurschnur || Identität des Agenten. |
| `constraints`, `decisions` | string[ || Benutzerbeschränkungen und vereinbarte Entscheidungen. |
| `success_criteria` | string[ || Beobachtbare Abschlussbedingungen. |
| `in_scope`, `out_of_scope` | string[ || Explizite Aufgabengrenzen. |
| `open_questions` | string[ || Ungelöste Fragen. |
| `direct_user_event_id` | Schnurschnur || Erforderlich für eine spätere Aufgaben- oder Vertragsrevision in derselben Sitzung. |
| `host_type` | Schnurschnur || `CODEX`, `CLAUDE`, `CUSTOM_MCP`, oder `CUSTOM_API`. |
| `integration_mode` | Schnurschnur || `ADVISORY` oder `ENFORCED`. |
| `confirmation_capable` | Boolean || Ob der Host den Sitzungsbenutzer inline fragen kann. |
| `effect_reporting_capable` | Boolean || Ob der Host tatsächliche Effekte melden kann. |

Nach dem Start, behalten `task.id`, `contract_version`und den zurückgebrachten Anker.

#### get\ task\ context

Holen Sie den aktiven Task Guard-Vertrag nach dem Start, der Verdichtung, dem Neustart oder wenn der Kontext veraltet ist.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `session_ref` | Schnurschnur | ✓ |

#### check\ task\ alignment

Überprüfen Sie eine vorgeschlagene materielle Aktion gegen die aktive Aufgabe, bevor Sie sie ausführen.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `session_ref` | Schnurschnur | ✓ | Stabile Sitzungsreferenz. |
| `action` | Schnurschnur | ✓ | Kurze Handlungsvorschläge. |
| `action_type` | Schnurschnur || Kategorie wie zum Beispiel `edit`, `read`, `send`, `create`, oder `execute`. |
| `target` | Schnurschnur || Datei, System, Person, Artefakt oder anderes Ziel. |
| `effects` | string[ || Erwartete direkte und verbundene Effekte. |
| `rationale` | Schnurschnur || Warum die Aktion die Aufgabe unterstützt. |
| `current_step` | Schnurschnur || Aktueller Aufgabenschritt. |
| `contract_version` | Nummer || Letzte Vertragsversion, die vom Gastgeber abgerufen wurde. |
| `external_action_id` | Schnurschnur || Stabile Host-Aktions-ID zur Bindung von Effektmeldungen. |
| `idempotency_key` | Schnurschnur || Stabiler Retry-Key. |
| `effect` | Schnurschnur || `READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`, oder `OTHER`. |
| `tool_name`, `operation` | Schnurschnur || Werkzeug und Bedienung werden überprüft. |
| `resource`, `destination` | Objekt || Strukturierte Ziel- und Zielmetadaten. |
| `data_classes` | string[ || Beteiligte Datenklassifikationen. |
| `reversible` | Boolean || Ob die Aktion rückgängig gemacht werden kann. |
| `estimated_cost` | Nummer || Geschätzte monetäre Kosten. |
| `provenance` | Schnurschnur || `HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`, oder `UNVERIFIED`. |
| `claimed_relationship` | Schnurschnur || Wie die Aktion die Aufgabe unterstützt: `DIRECT`, `REQUIRED_DEPENDENCY`, `COMPATIBILITY_REPAIR`, `VERIFICATION`, `SUPPORTING_RESEARCH`, `SUPPORTING_COORDINATION`, `INCIDENTAL_CLEANUP`, `OPTIONAL_IMPROVEMENT`, `OBJECTIVE_CHANGE`, `UNRELATED`, oder `UNKNOWN`. |

Folgen Sie der Rückkehr `verdict` und `next_action` genau. Siehe [Angleichungsurteile](https://maetra.io/de/docs/task-guard-api/alignment-and-effects#verdicts-and-required-behaviour).

#### explain\ task\ relationship

Beschränkte Beweise liefern, wenn `check_task_alignment` Rücksendungen `NEEDS_EXPLANATION`.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `check_id` | Schnurschnur | ✓ |
| `relationship` | Schnurschnur | ✓ |
| `evidence` | string[ ||

Die Antwort ist eine neue Anpassungsentscheidung. Folgen Sie seinem Urteil.

#### record\ task\ progress

Notieren Sie einen kompakten Meilenstein für die aktive Aufgabe.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `session_ref` | Schnurschnur | ✓ |
| `summary` | Schnurschnur | ✓ |
| `idempotency_key` | Schnurschnur | ✓ |
| `completed`, `next_steps` | string[ ||
| `new_dependencies`, `open_questions` | string[ ||
| `current_step` | Schnurschnur ||

Prüfen Sie alle `new_dependencies` Posten mit `check_task_alignment` bevor sie danach handeln.

#### record\ action\ effekt

Melden Sie, was eine zuvor überprüfte Aktion tatsächlich geändert hat.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `check_id` | Schnurschnur | ✓ |
| `actual_effects` | string[ | ✓ |
| `actual_effect` | Schnurschnur ||
| `affected_resources` | object[ ||
| `result_reference`, `artifact_hash` | Schnurschnur ||
| `summary`, `validation_outcome` | Schnurschnur ||

Wenn `effect_aligned` ist falsch, hör auf, die arbeit zu erweitern und frage den sitzungsbenutzer inline.

#### full\ task

Schließen Sie die aktive Task Guard-Aufgabe ab, wenn die Ziel- und Erfolgskriterien erfüllt sind.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `session_ref` | Schnurschnur | ✓ |
| `summary` | Schnurschnur | ✓ |
| `completion_event_id` | Schnurschnur | ✓ |

### Secure Werkzeuge

#### check\ action

Scannen Sie eine AI-Agent-Eingabeaufforderung, einen Werkzeugaufruf oder eine Ausgabe mit Maetra Secure. Rücken [`POST /v1/secure/scan`](https://maetra.io/de/docs/secure-api/scanning-content).

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `content` | Schnurschnur | ✓ | Prompt, Tool Payload oder Ausgabe zum Scannen. |
| `scan_type` | Schnurschnur || `prompt_input` (Standard) `tool_call`, oder `output`. |
| `tool_name` | Schnurschnur | ✓ wenn `tool_call` | Das Tool wird aufgerufen. |
| `agent_id`, `agent_name` | Schnurschnur || Identität des Agenten. |
| `context` | Objekt || Strukturierter Kontext. |

Ehrung `safe`, `flagged`, oder `blocked` Bevor wir fortfahren.

#### list\ active\ rules

Liste aktive Secure-Regeln auf. Keine Argumente darüber hinaus `mcp_access_token`.

#### create  rule

Erstellen Sie eine Secure-Regel. Neue Regeln standardmäßig `draft`.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `name` | Schnurschnur | ✓ | Name der Regel. |
| `type` | Schnurschnur | ✓ | `data_pattern`, `policy_dsl`, `prompt_pattern`, oder `tool_call`. |
| `action` | Schnurschnur || `block`, `flag`, oder `log`. |
| `severity` | Schnurschnur || `critical`, `high`, `medium`, oder `low`. |
| `status` | Schnurschnur || `active`, `archived`, oder `draft`. |
| `applies_to_all` | Boolean || Ausfälle bis `true`. |
| `data_direction` | Schnurschnur || `inbound`, `outbound`, oder `both`. |
| `custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids` | string[ || Regelspezifische Werte. |

#### update  rule

Aktualisieren Sie eine bestehende Secure-Regel nach ID. `id` ist erforderlich; jedes Create-Rule-Feld ist optional und nur eingereichte Felder ändern sich.

### Govern Werkzeuge

#### request

Fordern Sie einen Govern-Checkpoint an, bevor Sie eine Folgemaßnahme durchführen. Rücken [`POST /v1/checkpoints`](https://maetra.io/de/docs/govern-api/checkpoints).

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `action` | Schnurschnur | ✓ | Bezeichnung der Maßnahme. |
| `payload` | Objekt || Einzelheiten zu den strukturierten Maßnahmen. |
| `agent_id`, `agent_name` | Schnurschnur || Identität des Agenten. |
| `context`, `reasoning` | Schnurschnur || Reviewer Kontext und Agent Reasoning. |
| `autonomy_level` | Schnurschnur || `L0`–`L5`. |
| `policy_ids`, `policy_group_ids` | string[ || Beschränke die Bewertung. |
| `timeout_seconds` | Nummer || Wanduhr Decke für eine menschliche Entscheidung. |
| `idempotency_key` | Schnurschnur || Stabiler Retry-Schlüssel zum Erstellen des Checkpoints. |
| `target` | Objekt || Genaues Konto, Ressource, Ziel oder externes System. Erforderlich für die Ausführungsgenehmigung. |
| `task_authorization` | Objekt || Aufgabenbehörde mit `task_id`, `revision_id`, und `external_action_id`. Erforderlich für die Ausführungsgenehmigung. |
| `runtime` | Objekt || Versionierte Tool- oder Modellidentität. Erforderlich für die Ausführungsgenehmigung. |
| `executor_audience` | Schnurschnur || Intended Executor Identität. Ausfälle bis `maetra-executor`. |

Wenn die Antwort `pending`Weiterlesen über Polling with `get_approval_status`. Eine genehmigte Antwort ist die Entscheidung; Anruf `authorize_execution` unmittelbar vor der externen Aktion, um diese Genehmigung einmal zu konsumieren.

Eine genehmigte Antwort beinhaltet die unterzeichnete `decisionToken`, kanonisch `actionEnvelope`, `actionEnvelopeHash`, `policyDigest`, genau `policyVersions`, token lifecycle timestamps und die erwarteten ausführungs- und wirkungsfristen. Maetra führt diese Felder automatisch in die MCP-Ausführungswerkzeuge, wenn Sie die Checkpoint-ID angeben.

#### get\ approval\ status

Long-Poll ein Govern Checkpoint.

| Argumentation | Typ | erforderlich |
| -------- | ---- | -------- |
| `checkpoint_id` | Schnurschnur | ✓ |
| `wait_seconds` | Nummer ||

Pollen bis `approved`, `rejected`, `expired`, `blocked`, oder `cancelled`.

#### list\ active\ policies

Listen Sie aktive Govern-Richtlinien auf, einschließlich der Frage, ob jede genaue Regeln oder Entscheidungsintelligenz verwendet. Keine Argumente darüber hinaus `mcp_access_token`.

#### authorize\ ausführung

Verbrauchen Sie eine genehmigte Entscheidungsfähigkeit einmal, unmittelbar vor der genauen Anbieteranfrage. Maetra lädt den Checkpoint neu, überprüft die unterzeichnete Entscheidung und den kanonischen Aktionsumschlag und erstellt einen unterzeichneten Ausführungsbeleg.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `checkpoint_id` | Schnurschnur | ✓ | Genehmigter Checkpoint zurückgegeben von `request_approval`. |
| `idempotency_key` | Schnurschnur | ✓ | Stabiler Schlüssel für diese genaue Ausführung. Ein identischer Retry gibt die bestehende Autorisierung zurück. |
| `provider` | Schnurschnur | ✓ | Externer Anbieter oder System, der die Anfrage erhält. |
| `operation` | Schnurschnur | ✓ | Anbieterbetrieb, wie z.B. `refunds.create`. |
| `request` | JSON | ✓ | Normalisierte Downstream-Anfrage, die nach der Autorisierung gesendet wird. |

Rufen Sie den Anbieter nicht zuerst an. Eine geänderte Anfrage, ein falscher Vollstrecker, eine abgelaufene oder widerrufene Entscheidung oder eine zweite unabhängige Verwendung schlägt fehl. Provider-Retributionen bleiben unter den zurückgegebenen `executionId`.

#### record\ execution\ versuch

Fügen Sie einen unveränderlichen Anbieterversuch an die autorisierte Ausführung an. Aufzeichnung von Erfolgen, Misserfolgen, Timeouts und Wiederholungen gegen dieselben `execution_id`.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `execution_id` | Schnurschnur | ✓ | ID zurückgegeben von `authorize_execution`. |
| `attempt_number` | Nummer | ✓ | Positiver Versuchsablauf, beginnend bei `1`. |
| `request` | JSON | ✓ | Anfrage für diesen Provider-Versuch gesendet. |
| `response` | JSON || Antwort des Anbieters, sofern verfügbar. |
| `status` | Schnurschnur | ✓ | `succeeded`, `failed`, oder `unknown`. |
| `started_at` | Schnurschnur | ✓ | Startzeit des ISO 8601-Anbieters. |
| `completed_at` | Schnurschnur || Abschlusszeit nach ISO 8601, sofern bekannt. |
| `provider_status`, `provider_transaction_id`, `error_class` | Schnurschnur || Angaben zum Anbieterabgleich. |

Ein gescheiterter oder unbekannter Versuch verbraucht keine andere Entscheidung. Wiederholen Sie nur die identische autorisierte Aktion und notieren Sie dann die nächste Versuchsnummer.

#### record\ execution\ effect

Fügen Sie den nach der Hinrichtung beobachteten Zustand hinzu. Dies verbindet die genehmigte Aktion und den Anbieterversuch mit dem, was sich tatsächlich geändert hat.

| Argumentation | Typ | erforderlich | Beschreibung |
| -------- | ---- | -------- | ----------- |
| `execution_id` | Schnurschnur | ✓ | Die autorisierte Ausführung wird verifiziert. |
| `observation` | JSON | ✓ | Externer Zustand nach der Hinrichtung beobachtet. |
| `observed_at` | Schnurschnur | ✓ | Beobachtungszeit nach ISO 8601. |
| `verification_method` | Schnurschnur | ✓ | `provider_signed`, `ledger_readback`, `hardware_attested`, `stake_backed`, `task_guard`, oder `self_reported`. |
| `verification_status` | Schnurschnur || `verified`, `mismatch`, oder `unverified`; Standardwerte für `unverified`. |
| `proof` | JSON || methodenspezifischer Nachweis. |
| `provider`, `external_reference`, `task_guard_effect_report_id` | Schnurschnur || Verknüpfungen des Abgleichs. |

Selbstberichtete Beobachtungen bleiben gekennzeichnet `unverified`. Unabhängige verifizierungsmethoden erfordern, dass ihr konfigurierter verifier den beweis validiert; der anrufer kann eine nicht verifizierte beobachtung nicht in einen verifizierten beleg umwandeln, indem er einen booleschen festlegt.

### Mehrfachkontrollen bestellen

Für die gleiche materielle Aktion:

1. Anruf `check_task_alignment` Wenn Task Guard aktiviert ist.
2. Anruf `check_action` vor der Verarbeitung nicht vertrauenswürdiger Inhalte oder der Ausführung des Toolaufrufs.
3. Anruf `request_approval` vor der externen Aktion, wenn Govern aktiviert ist.
4. Umfrage, bis die Entscheidung terminal ist; stoppen, es sei denn, es ist genehmigt.
5. Anruf `authorize_execution` unmittelbar vor der genauen Anbieteranfrage.
6. Ausführen nur nach Autorisierung erfolgreich, dann aufrufen `record_execution_attempt` Für jeden Provider-Versuch.
7. Anruf `record_execution_effect` mit dem resultierenden beobachteten Zustand.
8. Anruf `record_action_effect` wenn die Task Guard-Effekt-Berichterstattung aktiviert ist.

Die Task Guard-Inline-Bestätigung ersetzt nicht die Govern-Genehmigung und die Govern-Genehmigung ersetzt nicht die One-Use-Ausführungsautorisierung.