Ende-zu-Ende Beispiel

Diese Seite zeigt den vollständigen Workflow mit jedem aktivierten Maetra-Steuerelement. Sie brauchen nicht jeden Schritt für jede Integration: Task Guard und Secure sind optional, und Ausführungsbelege sind für Teams, die eine Genehmigung mit der genauen Anbieteranfrage und dem beobachteten Ergebnis verbinden möchten.

Das Beispiel initialisiert die MCP-Sitzung, entdeckt fähigkeitsabhängige Werkzeuge, erhält ein Zugriffstoken, startet eine Task Guard-Aufgabe, überprüft eine materielle Aktion, führt Secure und Govern aus, zeichnet das Ergebnis auf und schließt die Aufgabe ab.

Ersetzen https://mcp.maetra.io Mit Deiner Distributed MCP Host.

1. Initialisieren#

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "billing-bot", "version": "0.1.0" }
  }
}

Die Antwort enthält Serveranweisungen für die im Arbeitsbereich aktivierten Funktionen.

2. Discover Werkzeuge#

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Das Ergebnis beinhaltet immer get_mcp_access, enthält dann nur die Task Guard-, Secure- und Govern-Tools, die für den aktuellen Arbeitsbereich und Schlüssel zugelassen sind.

3. Zugang zu Fähigkeiten erhalten#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_mcp_access",
    "arguments": {}
  }
}

Lesen structuredContent.mcp_access_token, expires_atund die aktivierten Fähigkeiten. Die folgenden Beispiele verwenden <ACCESS_TOKEN> für diesen kurzlebigen Wert.

Anruf get_mcp_access wieder zu Beginn jedes neuen Benutzerwechsels oder Arbeitszyklus.

4. Starten Sie die Aufgabe Task Guard#

Wenn Task Guard aktiviert ist:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "start_task",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "objective": "Process the approved customer refund.",
      "constraints": ["Do not modify unrelated customer records."],
      "success_criteria": ["Refund is processed and recorded."],
      "in_scope": ["Validate refund", "Request approval", "Execute refund"],
      "out_of_scope": ["Change billing provider configuration"],
      "agent_name": "billing-bot",
      "host_type": "CUSTOM_MCP",
      "confirmation_capable": true,
      "effect_reporting_capable": true,
      "idempotency_key": "task-start-01JY8Q"
    }
  }
}

Behalten Sie den zurückgegebenen Task-Anker und contract_version.

5. Überprüfung der Aufgabenausrichtung#

Vor der materiellen Aktion:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "action": "Submit a $5,000 refund to the billing provider",
      "action_type": "execute",
      "effect": "TRANSFER",
      "effects": ["Transfer $5,000 to the customer"],
      "tool_name": "billing_api",
      "operation": "create_refund",
      "contract_version": 1,
      "external_action_id": "refund-action-01JY8V",
      "idempotency_key": "alignment-01JY8V",
      "provenance": "HOST_VERIFIED"
    }
  }
}

Erlöse nur für ALIGNED oder SUPPORTING. Erklären NEEDS_EXPLANATIONFragen Sie den Benutzer inline nach USER_CONFIRMATION_REQUIREDRefresh-Kontext für CONTEXT_REFRESH_REQUIREDund umzuplanen oder zu stoppen für REFOCUS oder STOPPED.

6. Laufen Secure#

Wenn Secure aktiviert ist, scannen Sie den Toolaufruf vor der Ausführung:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "check_action",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "scan_type": "tool_call",
      "tool_name": "billing_api",
      "agent_name": "billing-bot",
      "content": "{\"operation\":\"create_refund\",\"amount\":5000,\"currency\":\"USD\"}"
    }
  }
}

Gehen Sie nicht vor, wenn Secure zurückkommt Blockiert. Überprüfung flagged entsprechend Ihrem Workflow.

7. Govern Genehmigung beantragen#

Wenn Govern aktiviert ist:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "request_approval",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "action": "transfer_funds",
      "agent_name": "billing-bot",
      "autonomy_level": "L3",
      "payload": { "amount": 5000, "currency": "USD", "to": "acct_9931" },
      "target": {
        "type": "customer_account",
        "id": "acct_9931",
        "provider": "northstar-billing"
      },
      "task_authorization": {
        "task_id": "<TASK_ID_FROM_START_TASK>",
        "revision_id": "<ACTIVE_TASK_REVISION_ID>",
        "external_action_id": "refund-action-01JY8V"
      },
      "runtime": {
        "tool_name": "billing_api",
        "tool_version": "4.2.0"
      },
      "executor_audience": "billing-worker",
      "idempotency_key": "refund-checkpoint-01JY8V",
      "reasoning": "Customer refund exceeds the auto-approve limit."
    }
  }
}

Wenn das Ergebnis anhängig, Umfrage:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_approval_status",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "checkpoint_id": "cp_7Yh2Qa",
      "wait_seconds": 30
    }
  }
}

Führen Sie die Umfrage bis zum Terminal durch. Stopp, es sei denn, das Ergebnis ist genehmigt. Die Genehmigung ist nicht der Anbieteraufruf: Der nächste Schritt verbraucht diese Genehmigung für eine genaue Ausführung.

8. Autorisieren Sie die genaue Ausführung#

Unmittelbar vor dem Aufruf des Abrechnungsanbieters:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "authorize_execution",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "checkpoint_id": "cp_7Yh2Qa",
      "idempotency_key": "refund-execution-01JY8V",
      "provider": "northstar-billing",
      "operation": "refunds.create",
      "request": {
        "amount": 5000,
        "currency": "USD",
        "customer_account": "acct_9931"
      }
    }
  }
}

Behalten Sie die zurückgegebene executionId. Senden Sie diese genaue Anfrage erst jetzt an den Anbieter. Wiederholen dieser Autorisierung mit dem gleichen Schlüssel und identischer Anforderung gibt die bestehende Quittung zurück; Ändern der Anforderungskonflikte.

9. Den Provider-Versuch aufzeichnen#

Nachdem der Anbieter geantwortet hat:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "record_execution_attempt",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "execution_id": "exec_01JY91",
      "attempt_number": 1,
      "request": {
        "amount": 5000,
        "currency": "USD",
        "customer_account": "acct_9931"
      },
      "response": {
        "refund_id": "rf_10492",
        "status": "succeeded"
      },
      "status": "succeeded",
      "provider_status": "201",
      "provider_transaction_id": "rf_10492",
      "started_at": "2026-08-12T09:15:02Z",
      "completed_at": "2026-08-12T09:15:03Z"
    }
  }
}

Für ein Timeout oder Misserfolg, verwenden failed oder unknown. Ein identischer Anbieter-Wiederholungsversuch bleibt unter der gleichen Ausführungs-ID und verwendet die Versuchsnummer 2.

10. Aufzeichnen des beobachteten Ausführungseffekts#

Lesen Sie den resultierenden Provider- oder Ledger-Status und fügen Sie ihn dann derselben Ausführung an:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "record_execution_effect",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "execution_id": "exec_01JY91",
      "observation": {
        "refund_id": "rf_10492",
        "amount": 5000,
        "currency": "USD",
        "status": "succeeded"
      },
      "observed_at": "2026-08-12T09:15:05Z",
      "verification_method": "self_reported",
      "provider": "northstar-billing",
      "external_reference": "rf_10492"
    }
  }
}

Dieses Beispiel verwendet self_reported, so dass die Quittung explizit bleibt unverified. Verwendung provider_signed, ledger_readbackoder ein anderes unabhängiges Verfahren nur dann, wenn der entsprechende Proof-Verifier konfiguriert ist.

11. Melden Sie den Effekt an Task Guard#

Wenn die Task Guard-Effekt-Berichterstattung aktiviert ist:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "record_action_effect",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "check_id": "tgc_01JY8W",
      "actual_effect": "TRANSFER",
      "actual_effects": ["Transferred $5,000 to customer account acct_9931"],
      "summary": "The approved refund completed successfully.",
      "validation_outcome": "Billing provider returned succeeded."
    }
  }
}

Wenn effect_aligned ist falsch, fragen Sie den Sitzungsbenutzer inline, bevor Sie weiter expandieren.

12. Abschluss der Aufgabe#

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "complete_task",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "summary": "The approved refund was processed and recorded.",
      "completion_event_id": "complete-01JY9Z"
    }
  }
}

Chargen#

Sie können unabhängige JSON-RPC-Anfragen wie z.B. initialize und tools/list. Nicht batchen get_mcp_access mit Fähigkeitsaufrufen, die ihr zurückgegebenes Token benötigen. Batch nicht sequentielle Task Guard, Secure, Govern, Ausführung und Effekt-Reporting-Schritte, deren Eingaben oder Berechtigung vom vorherigen Ergebnis abhängen.