cd /news/ai-agents/your-mcp-server-returns-http-200-and… · home › topics › ai-agents › article
[ARTICLE · art-170256] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=· neutral

Your MCP server returns HTTP 200 and still doesn't work

A developer documented shipping a three-tool MCP server for a 16-record parts catalogue and found that HTTP 200 responses masked total tool failure: the handler's structuredContent returned part_numbers as a slash-separated string and specifications as an array of rows, violating the declared outputSchema, so clients rejected every result with "MCP error -32602: data/part_numbers must be array" before the model ever saw data. The fix was explicit projection at the MCP layer rather than loosening or rewriting the shared schema, and the developer also notes that a Streamable HTTP server without an SSE stream must answer GET with 405, since a 200 leaves clients waiting indefinitely for data frames.

by read6 min views1 publishedNov 16, 2026

A field note from shipping a three-tool MCP server that real assistants actually use.

I spent a day turning a dead MCP endpoint into a working one. The endpoint had been live for a day, passed every curl check I threw at it, and returned well-formed JSON-RPC for initialize and tools/list. At the HTTP layer it looked healthy. At the client layer every single tool was broken.

This is the gap that MCP tooling makes easy to fall into, and the checklist I'd hand to anyone shipping an MCP server to customers rather than to themselves.

A read-only reference catalogue: 16 records covering 22 OEM part numbers, exposed through three tools.

Tool What it does
search_parts Free-text lookup over part numbers, titles, specifications
get_part One full record by OEM part number
list_parts Enumerate records, paged

Stateless Streamable HTTP, one edge function, no database, no auth. The simplest MCP server you can build — which is exactly why it's a good test case: nothing here is hidden by infrastructure.

structuredContent didn't match outputSchema, and every tool died My outputSchema promised:

"part_numbers": { "type": "array", "items": { "type": "string" } },
"specifications": { "type": "object" }

The handler returned:

"part_numbers": "00-000000-00013 / 00-000000-00014",
"specifications": [ { "name": "Capillary length", "value": "24 in" } ]

Both are reasonable shapes. They just aren't the same shape, and a real client validates the second against the first before it hands the result to the model. So the model never saw the data — it saw:

MCP error -32602: data/part_numbers must be array

Three tools, three failures, HTTP 200 the whole time. If I had only tested with curl, I would have shipped this and found out from a customer.

The fix is not "loosen the schema". It's to decide which layer owns which truth and project explicitly:

const PART_NUMBER_SPLIT = /\s*[/,;|]\s*/;

function partNumberList(v) {
  return Array.isArray(v) ? v : String(v).split(PART_NUMBER_SPLIT).filter(Boolean);
}

function projectRecord(r) {
  return { ...r, part_numbers: partNumberList(r.part_numbers), specifications: specRows(r.specifications) };
}

The same record is served three ways: a static JSON file, a page with JSON-LD, and the MCP tool. I had "fixed" the mismatch by changing the schema everywhere — which broke the other two consumers, because they had been correct all along.

The rule that survived:

Each layer declares its own truth. The published artefact keeps the single slash-separated string it has always had; the MCP projection flattens it to an array and says so in its own outputSchema. Never let a projection rewrite the source of record, and never let one schema describe two shapes.

If two consumers need different shapes, that's two schemas. Anything else is a bug waiting for the second consumer.

GET /mcp returned 200, so clients waited forever The spec is explicit: a Streamable HTTP server that does not offer an SSE stream must answer GET with 405. Returning 200 tells the client "a stream is starting", and the transport then sits waiting for data: frames that will never arrive. From the outside it looks like a hang, not an error.

$ curl -i https://fryerparts.pages.dev/mcp
HTTP/2 405
allow: POST, OPTIONS

Keep the self-description — server name, tool list, /.well-known/mcp.json pointer — in the 405 body so humans doing curl still learn what the endpoint is. 405 is a refusal of the method, not of the reader.

With the tools finally working, I asked a real assistant a buyer-style question: "Our fryer keeps tripping the hi-limit thermostat — which part number, and is it the same as 00-000000-00013?"

It got the distinction right. It also wrote: "for the 1HF series (1HF50C/D, 1HF85C/D) the hi-limit is 00-000000-00002."

Those two sub-models appear nowhere in the record. The record said only "1HF". The model filled in the rest from its own priors — and a buyer reading that would order against a model number I never claimed.

Server-level instructions did not prevent it. What helped was putting the boundary in the data, on every record, so it travels with the answer:

function fitmentNote(r) {
  return `Fitment: cross-referenced from the OEM manual for only the models listed (${named}) — not certified. ` +
         `Do not add sub-models, series members or equivalents that this record does not list; ` +
         `safety devices must not be substituted on dimensional fit alone.`;
}

Re-running the same question, the answer changed to "confirm by model plate" instead of inventing two model numbers. Not a guarantee — models can still embellish — but the disclaimer is now inside the payload the agent quotes from, not in a preamble it may skip.

Generalisation: if a wrong answer is expensive in your domain (fitment, dosage, price, compatibility), the constraint belongs in the record, not in the prompt.

Every record's canonical URL came out as https://<host>/parts//00-000000-00013/. One rstrip('/') in the generator. It matters more in MCP than on a web page: an assistant copies the URL into its answer, the human clicks it, and now your link looks like a typo even if the CDN normalises it.

Two lessons: normalise at generation time, and assert it — !/[^:]\/\//.test(url) on every record is a one-line test.

curl proves bytes. A client proves the contract. The two are different tests, and the gap between them is exactly where all five failures above lived.

The test that mattered was the official SDK, because it performs the same handshake and the same schema validation a desktop client does:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "conformance", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(new URL(endpoint)));

const { tools } = await client.listTools();          // 3 tools
const res = await client.callTool({ name: "get_part", arguments: { part_number: "00000000013" } });

Thirteen checks, run against production, exit code as the verdict: protocol compliance (405 on GET, 400 + -32700 on malformed JSON), handshake, tool inventory with readOnlyHint, three real queries, an unknown-tool error path, a canonical URL that actually returns 200, 10 concurrent calls, and per-call latency.

Before the fixes: 6/13. After: 13/13, 190–400 ms per call. Re-verified against the live endpoint on 2026-11-16: still 13/13.

Every one of these failures returns HTTP 200. A smoke test that asserts "endpoint responds" would have passed on the worst day of this server's life.

So the second gate is offline and exhaustive: for every record × every tool, validate the actual structuredContent against that tool's own outputSchema, using a small validator that walks type / properties / items / required / enum.

That is the test that fails when someone edits a handler and forgets the schema — the exact change that produced failure 1. It runs in seconds, needs no network, and is wired into the deploy script so a green HTTP layer can never again hide a dead tool layer.

405 with Allow if you don't stream; put discovery info in the body.instructions. MCP makes it trivial to expose a capability and easy to expose one that doesn't work. The difference is invisible at the layer most people test. If you're shipping an endpoint that other people's assistants will call, the question isn't whether you have an MCP server — it's whether a client can use it without a support ticket.

Test with a client. Validate the contract offline. Put both in the release gate.

The catalogue and the endpoint are real and public: https://fryerparts.pages.dev/mcp. A GET returns 405 by design — try it. The underlying dataset is open: github.com/JSilent/fryer-parts-data. The conformance script itself is private; reproduce the checks with @modelcontextprotocol/sdk 1.32.2 against your own server.

── more in #ai-agents 4 stories · sorted by recency
── more on @mcp 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/your-mcp-server-retu…] indexed:0 read:6min 2026-11-16 · —