feat(ENG-733): support flat_prefixed MCP param style
Problem
The SDK lists tools from /mcp without pinning a param-style, so the tool schema handed to the LLM follows the server default. Execution, however, goes through /actions/rpc with a hardcoded nested unwrap (path/query/headers/body). When the server default param-style flips nested → flat_prefixed, the LLM emits path_id/query_limit/… which the nested unwrap can't route: path and query params are dropped and the prefixed keys leak into the request body. The server-side MCP shim does not cover this — SDK execution bypasses the MCP transport and hits the actions RPC endpoint directly.
Fix
- Pin
?param-style=flat_prefixedon the/mcptool-listing endpoint, so the schema the LLM sees is stable regardless of the server default. - Replace the nested
_extract_recordunwrap with_split_envelope_params, which buckets<location>_<field>keys back intopath/query/headers/body. The prefix carries the location, so no per-action schema is needed. Bare nested envelopes are still accepted (for clients holding a cached nested schema), and unprefixed keys fall through to the body.
Net effect: SDK tool calls use the higher-accuracy flat_prefixed schema and are immune to the server-side default flip.
Tests
test_fetch_tools_pins_flat_prefixed_param_styletest_routes_flat_prefixed_keys_by_locationtest_buckets_nested_envelope_and_unprefixed_keys- Backward-compat preserved: existing nested/unprefixed execution tests unchanged.
tytype-check andruff(lint + format) clean.
Note
This protects SDK versions from this release forward. Already-published versions still break the moment the server default flips, so the server-side flip should be gated on quantifying old-version exposure by User-Agent.
Summary by cubic
Support the flat_prefixed MCP param style end-to-end so tool execution stays correct even if the server default changes. Addresses ENG-733 by pinning the /mcp schema and aligning RPC argument handling.
- Bug Fixes
- Pin
/mcp?param-style=flat_prefixedso tools expose<location>_<field>args consistently; tests assert the exact endpoint. - Replace the nested unwrap with
_split_envelope_paramsto bucketpath_/query_/headers_/body_-prefixed keys into the RPC envelope; still accepts nested dicts and treats unprefixed keys as body for backward compatibility.
- Pin