Metadaten

Eine MCP-tools/call-Anfrage kann Metadaten im Standardobjekt _meta mitführen. Ein generierter MCP-Server liest die folgenden Schlüssel daraus und bildet jeden auf einen Header des Aufrufs ab, den er an deine API richtet, falls deine API den Wert braucht:

Über deinen Tuix-Agenten

Jeder Tool-Aufruf, den dein Agent während eines Chats macht, trägt bereits beide Felder, automatisch, ohne dass etwas konfiguriert werden muss.

sessionId

_meta.sessionId wird auf die eigene sessionId dieser Unterhaltung gesetzt (siehe Anwendungs-Endpunkte). Akzeptiert deine API X-Session-Id, kannst du damit jeden Aufruf einer einzelnen Unterhaltung zuordnen.

idempotencyKey

_meta.idempotencyKey ist ein SHA-256-Hash (64 Hex-Zeichen), gebildet aus:

• der sessionId der Unterhaltung,
• dem aktuellen Turn, also der Nutzernachricht, auf die der Agent antwortet,
• dem Namen des Tools,
• den Argumenten des Tools. Argumente mit null oder leeren Strings werden ignoriert, und die Reihenfolge der Argumente ändert den Schlüssel nicht.

Dasselbe Tool mit denselben Argumenten erzeugt bei der Antwort auf dieselbe Nachricht immer denselben Schlüssel. Ein anderes Tool, andere Argumente, eine neue Nachricht oder eine neue Unterhaltung erzeugen einen anderen Schlüssel.

So kann das System hinter deiner API erkennen, wenn sich das Modell wiederholt, z. B. ein Modell, das in einer Schleife immer wieder create_invoice mit identischen Daten aufruft. Akzeptiert deine API X-Idempotency-Key, kannst du damit entscheiden, ob eine eingehende Anfrage neu und gültig oder ein Duplikat ist:

• Bereits gesehen: Der Aufruf wiederholt einen bereits verarbeiteten. Gib das vorherige Ergebnis zurück oder lehne ihn ab, statt die Rechnung ein zweites Mal zu erstellen.
• Neuer Schlüssel: Die Anfrage enthält neue Parameter (oder stammt aus einer neuen Nachricht) und kann normal verarbeitet werden.

Einen generierten Server direkt aufrufen

Wenn du dich selbst mit einem generierten Server verbindest, setze _meta.sessionId und/oder _meta.idempotencyKey in deinen eigenen tools/call-Anfragen, damit sie weitergeleitet werden:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_employees",
        "arguments": { "page": 1 },
        "_meta": {
            "sessionId": "your-own-session-id",
            "idempotencyKey": "your-own-idempotency-key"
        }
    }
}

Der Server liest beide Felder aus _meta und sendet deiner API X-Session-Id: your-own-session-id und X-Idempotency-Key: your-own-idempotency-key, zusammen mit dem Authorization- oder X-Api-Key-Header, den der Aufruf trägt, siehe Autorisierung. Beim direkten Aufruf entscheidest du selbst, wie du den Schlüssel bildest; jeder Wert, der für Aufrufe gleich bleibt, die du als Duplikate betrachtest, funktioniert.