OpenAPI request director sends multipart/form-data and form-urlencoded as JSON, drops cookies

[strawgate]

The request director detects the declared content type from the OpenAPI spec but only implements the JSON branch. Non-JSON content types silently fall through to application/json.

multipart/form-data → JSON

An OpenAPI endpoint declaring multipart/form-data (e.g., file uploads) sends the body as application/json:

# OpenAPI spec says: content: { "multipart/form-data": ... }
# Actual request: Content-Type: application/json, body: {"file": "data"}
# Expected:       Content-Type: multipart/form-data; boundary=...

application/x-www-form-urlencoded → JSON

Same issue — form submissions are sent as JSON:

# OpenAPI spec says: content: { "application/x-www-form-urlencoded": ... }
# Actual request: Content-Type: application/json, body: {"username": "admin"}
# Expected:       Content-Type: application/x-www-form-urlencoded, body: username=admin

Cookie parameters silently dropped

_unflatten_arguments() handles path, query, header, and body locations but has no cookie case. Cookie parameters log a warning and are lost.

All three are in src/fastmcp/utilities/openapi/director.py. The content type is detected at line 79-81 but never dispatched on for non-JSON types.

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 38s —— View job

---

tl;dr

Bug confirmed — the director's body-dispatch at src/fastmcp/utilities/openapi/director.py:84-101 only implements the JSON branch, and _unflatten_arguments has no cookie case (director.py:147-158). Draft PR #3932 already implements a fix (author: @strawgate) but is marked [DNM] / DON'T MERGE. Recommendation below plus an action plan for when the author is ready to flip it out of draft.

Recommendation

Fix in-place in RequestDirector.build — dispatch on declared_content_type to httpx's native encoders (files= for multipart, data= for form-urlencoded) and add a cookie branch to _unflatten_arguments that flows through to httpx.Request(cookies=...). Do not introduce a new module or per-content-type class hierarchy — there are only 3 form types the spec actually defines, and httpx already handles the encoding. Keep the change surgical so the existing invariants (query style/explode, path param encoding) are untouched.

PR #3932 takes exactly this approach and is a solid starting point. A few things to verify before promoting it out of draft (see the action plan).

Findings

Bug 1 — multipart/form-data dispatched as JSON. director.py:84-101 only branches on "json" in declared_content_type. Any other content type with a dict body falls into the else: json_body = body path (line 99), and httpx serializes with Content-Type: application/json. The existing test test_non_json_content_type_falls_through (tests/utilities/openapi/test_director.py:533-557) literally asserts this broken behavior with the comment "Should fall through to httpx's json= path … since the content type isn't JSON-compatible" — so this regression is locked in by a test and will need its assertion flipped.

Bug 2 — application/x-www-form-urlencoded dispatched as JSON. Same code path. httpx's data=<dict> produces the correct application/x-www-form-urlencoded encoding but the director never uses it.

Bug 3 — cookie parameters silently dropped. _convert_to_parameter_location (parser.py:148) accepts "cookie" and ParameterLocation in models.py:13 includes it, so cookie params reach the director. But _unflatten_arguments only dispatches on path/query/header/body (primary path director.py:147-158, fallback path director.py:174-183). Cookie params fall through to the "Unknown parameter location" warning and are discarded. httpx.Request already supports cookies=, so the wiring is trivial once unflatten collects them.

Historical context. PR #3611 ("Respect OpenAPI content type in request body serialization") added the "json" in declared_content_type branch for JSON variants like application/merge-patch+json. That PR explicitly did not extend to non-JSON types — this issue is completing the work.

Existing fix PR. #3932 is open as [DNM] and implements all three fixes. Since the author of the PR is the author of this issue (@strawgate), the DNM label likely signals "not ready for review yet" rather than a blocker; the maintainer should confirm before acting.

Detailed Action Plan

Assuming #3932 is the landing vehicle, here's what a reviewer should check / a junior dev should verify:

1. Content-type dispatch order in build()
The dispatch should happen before the existing JSON branch and only when body is a dict. Keep the order:

1. multipart/form-data + dict → httpx.Request(files=…)
2. application/x-www-form-urlencoded + dict → httpx.Request(data=…)
3. JSON-compatible ("json" in declared_content_type) → manual serialization + explicit header (existing logic)
4. Else dict/list → json= (httpx default)
5. Else (bytes/str) → content= (existing)

2. Multipart file handling. #3932 wraps each value as (None, value) so httpx treats them as form fields not file uploads. That's correct for string payloads, but real file-upload use cases want (filename, content, content_type). The current body_props dict is populated from flat scalar args by _unflatten_arguments — it can't carry a filename today. For a first cut, the (None, value) wrapper is acceptable; file-upload ergonomics can be a follow-up. Worth a PR comment noting this limitation.

3. Cookie unflatten. Add cookie_params: dict[str, Any] as a 4th element returned from _unflatten_arguments, populate it in both the primary parameter-map path and the fallback __cookie suffix path, and thread it to httpx.Request(cookies=…). #3932 does this.

4. Flip the existing assertion. test_non_json_content_type_falls_through at tests/utilities/openapi/test_director.py:533 must change. Rename to test_multipart_form_data_uses_native_encoding, assert "multipart/form-data" in content-type.

5. New tests to add (all in test_director.py):

• multipart dispatch: body encoded as multipart, CT header has boundary=, each property present in body bytes
• urlencoded dispatch: CT == "application/x-www-form-urlencoded", body is username=admin&password=… (order-insensitive)
• cookie dispatch (primary path): request.headers["cookie"] contains session=abc
• cookie dispatch (fallback __cookie suffix): same assertion
• JSON path unchanged: existing tests still pass
• Edge: multipart/form-data with empty body dict should not crash
• Edge: body is a non-dict (list/scalar) with multipart/form-data declared — should not take the multipart branch (the condition in fix: OpenAPI request director sends multipart and form-urlencoded as JSON #3932 already guards with isinstance(body, dict), verify)

6. Docs. Check docs/ for any statement that OpenAPI integration supports "JSON bodies only" — if present, update. No schema changes.

7. Validate. uv run pytest tests/utilities/openapi/test_director.py -n auto then uv run prek run --all-files.

8. PR hygiene. Ask @strawgate to remove the [DNM] label/title prefix when ready, and to split the title into a non-[DNM] version like fix: dispatch non-JSON content types and cookie params in OpenAPI director.

Related Items

Repo	Issue/PR	Relevance
PrefectHQ/fastmcp	#3932	Draft [DNM] fix by the issue author implementing all three bugs. Almost mergeable.
PrefectHQ/fastmcp	#3611	Earlier fix that added JSON-variant content-type handling. This issue completes its work for non-JSON types.
PrefectHQ/fastmcp	#3595	Related director fix (query param explode) — different area but same file.

Related Files

File	Relevance	Lines
src/fastmcp/utilities/openapi/director.py	Body dispatch and _unflatten_arguments — all three bugs live here	79-101, 147-158
src/fastmcp/utilities/openapi/models.py	ParameterLocation type already includes "cookie"	13
src/fastmcp/utilities/openapi/parser.py	Parser already accepts "cookie" params — they flow through to the director	148
tests/utilities/openapi/test_director.py	Contains the test that locks in the current broken behavior — must be updated	533-557

Related Webpages

Name	URL	Relevance
httpx Request API — files, data, cookies	https://www.python-httpx.org/api/#request	Confirms files= produces multipart, data=<dict> produces urlencoded, cookies= sets Cookie header
OpenAPI 3.0 Parameter Locations (incl. cookie)	https://swagger.io/docs/specification/describing-parameters/	Confirms cookie is a first-class parameter location
OpenAPI Request Body content types	https://swagger.io/docs/specification/describing-request-body/	Confirms multipart/form-data and x-www-form-urlencoded are first-class request body types

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[itsmejay80]

This was fixed in #3932 (merged 2026-04-14). The director now dispatches on the declared content type multipart/form-data uses httpx's files=, application/x-www-form-urlencoded uses data=, and cookie params flow through _unflatten_arguments to httpx.Request(cookies=...). Safe to close.

[jlowin]

Fixed by #3932 (merged 2026-04-14).