{"slug": "your-mcp-server-returns-http-200-and-still-doesn-t-work", "title": "Your MCP server returns HTTP 200 and still doesn't work", "summary": "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.", "body_md": "*A field note from shipping a three-tool MCP server that real assistants actually use.*\n\nI 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.\n\nThis 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.\n\nA read-only reference catalogue: 16 records covering 22 OEM part numbers, exposed through three tools.\n\n| Tool | What it does | \n|---|---|\n| `search_parts` | Free-text lookup over part numbers, titles, specifications | \n| `get_part` | One full record by OEM part number | \n| `list_parts` | Enumerate records, paged | \n\nStateless 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.\n\n`structuredContent` didn't match `outputSchema`, and every tool died\nMy `outputSchema` promised:\n\n```\n\"part_numbers\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n\"specifications\": { \"type\": \"object\" }\n```\n\nThe handler returned:\n\n```\n\"part_numbers\": \"00-000000-00013 / 00-000000-00014\",\n\"specifications\": [ { \"name\": \"Capillary length\", \"value\": \"24 in\" } ]\n```\n\nBoth 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:\n\n```\nMCP error -32602: data/part_numbers must be array\n```\n\nThree 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.\n\n**The fix is not \"loosen the schema\".** It's to decide which layer owns which truth and project explicitly:\n\n``` js\nconst PART_NUMBER_SPLIT = /\\s*[/,;|]\\s*/;\n\nfunction partNumberList(v) {\n  return Array.isArray(v) ? v : String(v).split(PART_NUMBER_SPLIT).filter(Boolean);\n}\n\nfunction projectRecord(r) {\n  return { ...r, part_numbers: partNumberList(r.part_numbers), specifications: specRows(r.specifications) };\n}\n```\n\nThe 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.\n\nThe rule that survived:\n\nEach 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.\n\nIf two consumers need different shapes, that's two schemas. Anything else is a bug waiting for the second consumer.\n\n`GET /mcp` returned 200, so clients waited forever\nThe 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.\n\n``` bash\n$ curl -i https://fryerparts.pages.dev/mcp\nHTTP/2 405\nallow: POST, OPTIONS\n```\n\nKeep 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*.\n\nWith 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?\"*\n\nIt got the distinction right. It also wrote: *\"for the 1HF series (1HF50C/D, 1HF85C/D) the hi-limit is 00-000000-00002.\"*\n\nThose 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.\n\nServer-level `instructions` did not prevent it. What helped was putting the boundary **in the data**, on every record, so it travels with the answer:\n\n```\nfunction fitmentNote(r) {\n  return `Fitment: cross-referenced from the OEM manual for only the models listed (${named}) — not certified. ` +\n         `Do not add sub-models, series members or equivalents that this record does not list; ` +\n         `safety devices must not be substituted on dimensional fit alone.`;\n}\n```\n\nRe-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.\n\n**Generalisation:** if a wrong answer is expensive in your domain (fitment, dosage, price, compatibility), the constraint belongs in the record, not in the prompt.\n\nEvery 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.\n\nTwo lessons: normalise at generation time, and assert it — `!/[^:]\\/\\//.test(url)` on every record is a one-line test.\n\n`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.\n\nThe test that mattered was the official SDK, because it performs the same handshake and the same schema validation a desktop client does:\n\n``` js\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nconst client = new Client({ name: \"conformance\", version: \"1.0.0\" });\nawait client.connect(new StreamableHTTPClientTransport(new URL(endpoint)));\n\nconst { tools } = await client.listTools();          // 3 tools\nconst res = await client.callTool({ name: \"get_part\", arguments: { part_number: \"00000000013\" } });\n```\n\nThirteen 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.\n\nBefore 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.\n\nEvery 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.\n\nSo 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`.\n\nThat 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.\n\n`405` with `Allow` if you don't stream; put discovery info in the body.`instructions`.\nMCP 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.\n\nTest with a client. Validate the contract offline. Put both in the release gate.\n\n*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.*", "url": "https://wpnews.pro/news/your-mcp-server-returns-http-200-and-still-doesn-t-work", "canonical_source": "https://dev.to/kyle_xue_0ca4d442673e23c0/your-mcp-server-returns-http-200-and-still-doesnt-work-5354", "published_at": "2026-11-16 03:43:04+00:00", "updated_at": "2026-11-16 03:51:01.431211+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["MCP", "Streamable HTTP", "JSON-RPC", "JSON-LD"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-mcp-server-returns-http-200-and-still-doesn-t-work", "markdown": "https://wpnews.pro/news/your-mcp-server-returns-http-200-and-still-doesn-t-work.md", "text": "https://wpnews.pro/news/your-mcp-server-returns-http-200-and-still-doesn-t-work.txt", "jsonld": "https://wpnews.pro/news/your-mcp-server-returns-http-200-and-still-doesn-t-work.jsonld"}}