Metadata

An MCP tools/call request can carry metadata in the standard _meta object. A generated MCP server reads the following keys from it, mapping each one to a header on the call it makes to your API, in case your API needs the value:

Through your Tuix agent

Every tool call your agent makes during a chat already carries both fields, automatically, nothing to configure.

sessionId

_meta.sessionId is set to that conversation's own sessionId (see Application endpoints). If your API accepts X-Session-Id, you can use it to correlate every call a single conversation makes.

idempotencyKey

_meta.idempotencyKey is a SHA-256 hash (64 hex characters) built from:

• the conversation's sessionId,
• the current turn, i.e. the user message the agent is answering,
• the tool name,
• the tool arguments. Arguments that are null or empty strings are ignored, and the order of the arguments doesn't change the key.

The same tool called with the same arguments while answering the same message always produces the same key. A different tool, different arguments, a new message or a new conversation produces a different key.

This lets the system behind your API detect when the model repeats itself, e.g. a model stuck in a loop calling create_invoice over and over with identical data. If your API accepts X-Idempotency-Key, you can use it to decide whether an incoming request is new and valid or a duplicate:

• Seen before: the call is a repeat of one already processed. Return the previous result, or reject it, instead of creating the invoice twice.
• New key: the request carries new parameters (or comes from a new message) and can be processed normally.

Calling a generated server directly

If you connect to a generated server yourself, set _meta.sessionId and/or _meta.idempotencyKey on your own tools/call requests to have them forwarded:

{
    "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"
        }
    }
}

The server reads both fields from _meta and sends your API X-Session-Id: your-own-session-id and X-Idempotency-Key: your-own-idempotency-key, alongside whatever Authorization or X-Api-Key header the call carries, see Authorization. When calling directly, you choose how to build the key; any value that stays the same for repeated calls you consider duplicates works.