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.
The setup
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.
Failure 1 — 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) };
}
Failure 2 — the published JSON and the MCP projection are two different contracts
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.
Failure 3 — 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.
Failure 4 — the model embellished, and instructions didn't stop it
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.
Failure 5 — agents quote URLs verbatim, including your broken ones
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.
Failure 6 — only a real client finds this class of bug
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.
Failure 7 — the bug was invisible to CI, so it could ship again
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.
The checklist
- Return
structuredContentthat validates against your ownoutputSchema— and test it, per record, per tool. - One schema per shape. Published artefacts and projections get separate contracts.
-
GET /mcp→405withAllowif you don't stream; put discovery info in the body. - Keep deterministic work deterministic — but that's a separate post.
- Put expensive-to-get-wrong constraints in the payload, not in
instructions. - Normalise URLs and assert on them; agents quote what you give them.
- Gate the deploy on the contract test, not on a status-code smoke test.
Why this is worth writing down
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: https://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.
Top comments (1)
Interesting that it passed the HTTP tests but still failed the 3 tools due to schema mismatches. The fact that we are using a real MCP client to test rather than just curl is very important. Was using the official SDK tests helpful for catching these issues early?