NOV 15, 2026

Out of the box, an MCP server answers curl with a 406

The SDK enforces the spec's Accept rule literally, so a wildcard or a missing Accept header is refused before the handshake starts. The fix is one small file, it needed a second round after an outside audit, and it is the most load-bearing file on the surface.

mcphttpinterop

The lab's MCP server is public and needs no token, because everything it exposes is already on the site. The point of that is that anything can try it. Left to the SDK's defaults, most things could not.

What happened

The Streamable HTTP spec says a client MUST list both application/json and text/event-stream in its Accept header. The SDK the server is built on enforces that word for word: anything else is answered 406 before the initialize call is even read.

Real clients do not send that pair. curl sends */*. Most HTTP libraries send */* or nothing. Audit crawlers send whatever their HTTP stack defaults to. Under RFC 9110 a wildcard range accepts both media types, and a missing Accept header means no preference at all. So a server refusing those requests is not enforcing the spec against a broken client. It is failing to interoperate with a correct one.

lib/mcp-transport.ts shipped with the route on 2026-08-26 and sits between it and the SDK. It makes two decisions at the boundary:

  1. Admission. If the client's Accept would take either representation under RFC 9110 matching, hand the SDK the exact header it insists on.
  2. Representation. Answer in JSON unless the client actually prefers the stream, by naming it alone or ranking it above JSON with a q-value. This server holds no subscriptions and sends no progress notifications, so a single request and response never needs a stream to be correct, and JSON is the format nothing has ever failed to parse.

A day later an external agent-readiness audit still reported a failed handshake. The cause was Accept: text/*. The transport used "names the subtype outright" for two different questions, whether to admit a client and which format it prefers, so a text/* client scored zero for both, fell through, and got a 406 from a server that could have answered it. Admission now uses wildcard-aware matching; preference still requires the type to be named. The fix shipped with a regression guard on every shape that already worked.

What the production server answers today, to an initialize POST:

Accept               status  content-type
*/*                  200     application/json
(none)               200     application/json
application/json     200     application/json
text/*               200     text/event-stream
text/plain           406     application/json

The last row is the only refusal, and it is deliberate: a client that takes neither format is owed a 406, because there is nothing honest left to send it.

What it cost

Two rounds, and the second came from outside. The first fix was tested against the shapes I thought of. The audit found the one I had not, and it was a shape the RFC answers in one sentence. A unit test that enumerates the cases you imagined only proves you imagined them.

What I would do differently

Fire the handshake shapes at the deployed server from day one instead of reasoning about them. That is what /bench does now: one probe per shape in its CLIENTS group, run against this deployment, with the response on screen. It also answers at /mcp, re-exported from the real route rather than reimplemented, because that is the path clients and scanners guess first.

The general lesson is about where the bug lives. "MUST" in a spec describes what a well-behaved client sends. It is not a licence for the server to refuse everything else. The robust reading is to accept what the RFCs say is acceptable and let the strict rule govern what you send.