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

> Source: <https://dev.to/kyle_xue_0ca4d442673e23c0/your-mcp-server-returns-http-200-and-still-doesnt-work-5354>
> Published: 2026-11-16 03:43:04+00:00

*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:

``` js
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.

``` bash
$ 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:

``` js
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.*
