MCP unsupported_payload_keys: read the allowed array

Sume's hosted MCP tools check the payload against a list of allowed keys. A key outside that list is not ignored. The call fails with the code unsupported_payload_keys before any job is created. This differs from unsupported_tool_arguments, which is about keys next to the payload; here the unknown key is inside it.

The shape of the error

The message says the tool payload has unsupported keys. The data carries unexpected, the array of keys that were refused; allowed, the full list the tool accepts; and tool, the tool name. When the unknown key is nested, the message adds the location, such as unsupported keys at a path, and the data includes a path field.

The allowed list mirrors the public OpenAPI request for the matching REST route. So the list you receive follows the public API contract for that tool.

A fix that works every time

Do not delete the key and retry blindly. Compare unexpected with allowed. Often the key is a near miss, such as a field from another model's request. If a tool adds a hint, follow it: for music_create the message says Music 1.0 is prompt-driven and that duration and duration_seconds must not be sent.

Keep the same idempotency_key on the corrected call. The first call never ran, so there is nothing to duplicate.

// refused
{ "idempotency_key": "clip-41", "payload": { "prompt": "a calm lake", "fps_boost": true } }

// error data (shape)
{ "code": "unsupported_payload_keys", "unexpected": ["fps_boost"], "allowed": ["prompt", "..."], "tool": "generate_video" }

Make the agent do it

Give the agent one rule in its system prompt: when a call fails with unsupported_payload_keys, drop only the keys in unexpected, check them against allowed, and retry once. Without the rule, models tend to rewrite the whole payload and introduce a new bad key. Log the tool and unexpected values; they show which fields your prompts keep inventing.