DEV Community: Martin Havel

Your MCP Server Passes Every Test — and Claude Still Rejects the Tool

Martin Havel — Wed, 10 Jun 2026 16:20:37 +0000

We shipped what looked like a routine improvement to one of our MCP tools: a declared outputSchema, generated from our existing Zod types. Server-side smoke tests passed. The structured output validated cleanly against JSON Schema 2020-12 with an independent validator. We deployed.

Then Claude Desktop refused to call the tool at all.

This post is a write-up of that incident—what failed, why all our tests missed it, and what an actual end-to-end test for an MCP server needs to look like. One caveat up front: this is n=1, observed on our specific setup (@modelcontextprotocol/sdk ^1.10, zodToJsonSchema, Claude Desktop as the client, June 2026). Treat it as a mechanism worth knowing about, not a universal law.

"MCP tool not showing up": outputSchema rejected by the client ingest layer

That heading is the literal symptom, because it's what you'll be searching for at 11 p.m. The variants we tried ourselves: MCP tool not showing up, outputSchema rejected, MCP tool ingest failed, Claude Desktop tool error request_id.

Here's what we saw, concretely:

Calling the tool from Claude Desktop produced an error carrying a request_id—the request reached Anthropic's side and was rejected there.
Our server logs showed a new session line and then... nothing. No [tool] invocation line. The call never arrived at our handler.
A curl against our own server with the same payload? Worked perfectly. Valid response, valid structuredContent.

So the tool definition itself was being rejected somewhere between the client and our server—at what I'll call the tool-ingest layer: the validation Anthropic's infrastructure runs on tool definitions before the model is ever allowed to use them. Our server was never consulted.

The setup: adding outputSchema via zodToJsonSchema

The tool in question was watch_entity from our open-source Czech company due-diligence MCP server (cz-agents on GitHub). We already returned structuredContent and wanted to declare its shape, which the MCP spec supports via outputSchema:

import { zodToJsonSchema } from "zod-to-json-schema";

const watchEntityOutput = z.object({
  ico: z.string(),
  status: z.literal("watching"),
  expires_at: z.string().nullable(),  // <- this matters later
});

server.registerTool(
  "watch_entity",
  {
    description: "Watch a Czech company for changes",
    inputSchema: watchEntityInput,
    outputSchema: zodToJsonSchema(watchEntityOutput), // <- the change
  },
  handler
);

Looks innocent. But look at what zodToJsonSchema actually emits by default:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "ico": { "type": "string" },
    "status": { "const": "watching" },
    "expires_at": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  },
  "required": ["ico", "status", "expires_at"]
}

Three constructs in this schema are worth noticing:

The $schema URI is draft-07, not the JSON Schema 2020-12 dialect the MCP spec gravitates toward.
z.null() / .nullable() produces "type": "null" branches.
z.literal() produces const.

All three are completely standard JSON Schema. Every off-the-shelf validator we threw at this—including an independent jsonschema check of our structuredContent against the schema—passed without complaint.

But the ingest layer that vets tool definitions on Anthropic's side was, at the time we hit this, stricter than a generic validator. It didn't accept this combination, and the failure mode wasn't "schema ignored"—it was the entire tool being rejected.

I want to be careful with framing here: this isn't a story about anyone doing something wrong. The SDK emitted valid draft-07. Our validator correctly validated it. The ingest layer enforced a tighter profile than "any valid JSON Schema." Validation layers differ, and the only place all of them meet is a live round-trip. That lesson survives even if the ingest layer accepts these constructs tomorrow.

The diagnostic key: asymmetry

What saved us from days of wrong theories was one observation: only the tool with outputSchema failed. Our text-only tool on the same server, same session, same deploy—get_dd_report—kept working the whole time.

That asymmetry rules out almost everything else you'd suspect first:

A network or transport issue would hit both tools.
A server crash or bad deploy would hit both tools.
A client-side transient would not reproduce selectively, every time, on exactly one tool.

A generic outage doesn't aim. When one tool fails deterministically and its siblings don't, diff the tool definitions, not the infrastructure. In our case, the diff was one field: outputSchema.

The second diagnostic key was the log shape. A new session line with no [tool] line means the handshake happened but the tool call was never dispatched to us. Combined with an error that carries a request_id, that places the rejection firmly on the ingest side—not in our process, not in the user's network.

The fix: drop outputSchema, keep structuredContent

Here's the part that surprised me: structuredContent works fine without a declared outputSchema. The schema declaration is metadata; the structured payload travels regardless.

server.registerTool(
  "watch_entity",
  {
    description: "Watch a Czech company for changes",
    inputSchema: watchEntityInput,
    // outputSchema removed — structuredContent still flows
  },
  async (args) => {
    const result = await watchEntity(args);
    return {
      content: [{ type: "text", text: summarize(result) }],
      structuredContent: result, // <- still delivered to the client
    };
  }
);

We removed the outputSchema declaration, redeployed, and the end-to-end flow worked perfectly: Claude Desktop called the tool, the [tool] line showed up in docker logs, and structured content arrived at the client. You lose client-side schema validation of your output, which is a real (if modest) loss—but you keep the structured data, and you keep a working tool.

If you do want to keep outputSchema, the cautious path based on what we observed is to post-process the generated schema—strip the draft-07 $schema URI, replace "type": "null" branches with a non-null type plus optionality, replace const with a single-value enum—and then test it through a real client before trusting it. Which brings us to the actual point.

Why your curl smoke test will never catch this

Our smoke test did what most MCP smoke tests do: hit the server over HTTP, list tools, call each one, and validate the response. It's a fine test of our code. It exercises exactly zero of the validation that happens on the client/platform side.

The chain for a hosted MCP tool call looks roughly like this:

Claude (model) → Anthropic tool-ingest/validation → your MCP server → back

A curl test starts at step 3. Everything that can reject your tool in steps 1–2—schema dialect restrictions, definition size limits, naming rules, whatever else the platform enforces—is invisible to it. Server-side green means "my half works," and nothing more.

So our deploy checklist gained one non-negotiable step. The real E2E test for an MCP server is a live client round-trip:

Deploy to a staging endpoint.
Connect a real Claude client (Claude Desktop, claude.ai, or Claude Code) to it.
Ask it to invoke every tool—especially any tool whose definition changed, not just its handler.
Watch your server logs for the invocation marker. For us: docker logs -f mcp-server | grep '\[tool\]'. A session line without a tool line indicates a rejection upstream of your server.
Confirm the result rendered correctly in the client.

It's manual, it's slightly annoying, and it takes five minutes. It is also the only test in our suite that would have caught this—and the only one that exercises the same path your users do.

Takeaways

A tool definition change is riskier than a handler change: it gets re-validated by every layer between you and the model, and the failure mode is the whole tool disappearing.
zodToJsonSchema defaults to draft-07 with type: "null" and const—valid JSON Schema that stricter ingest profiles may not accept. Inspect the generated schema; don't assume.
Selective failure is information. One tool down, siblings up → diff the definitions.
A new session log line without a [tool] log line localizes the rejection upstream of your server.
structuredContent does not require outputSchema. When in doubt, ship the data without the declaration.
Server-side smoke tests validate your half of the contract. Only a live Claude client round-trip validates the whole thing. Put one in your deploy checklist.

*Observed June 2026 on @modelcontextprotocol/sdk ^1.10 with Claude Desktop. If the ingest behavior has changed since, the specific constructs may pass—the testing lesson stands either way. The server involved is open source: cz-agents MCP servers

I built a free, browser-only European payment QR generator (and an MCP server)

Martin Havel — Mon, 01 Jun 2026 13:41:27 +0000

Every time I get an invoice or a broker deposit instruction, I do the same dumb, error-prone thing: copy the IBAN, the amount, and the variable symbol into my banking app by hand. One transposed digit and the money goes to a stranger.

Czech invoices increasingly carry a QR Platba code you just scan — but a lot of them still don't (anyone invoicing from Word/Excel, foreign senders, smaller shops). So I built a small tool that turns those payment details into a scannable QR, and it grew into something I think is worth sharing.

Live: https://qr.cz-agents.dev · Code (MIT): https://github.com/martinhavel/cz-agents-mcp · npm: @czagents/payqr

What it does

Generates SPAYD (Czech/Slovak "QR Platba") and EPC / GiroCode (the SEPA standard, huge in Germany/Austria) payment QR codes from an IBAN + amount + reference.
Also does plain-text, Wi-Fi and vCard QR, and reads a QR back (decode + classify).
You can type the details or drop a payment screenshot — OCR runs in your browser.
The lazy path (in an AI client / MCP): hand it a whole invoice — PDF or photo — and the model reads the IBAN, amount and reference and generates the payment QR for you. No retyping at all, with a verify step before anything is shown.
It's 100% client-side: nothing is uploaded, no account, no tracking, no AI, MIT.

The bits that were actually interesting to build

1. The payment formats are just strings. SPAYD is a delimited string:

SPD*1.0*ACC:CZ6508000000192000145399*AM:1250.00*CC:CZK*X-VS:1234567890

EPC/GiroCode is 12 newline-separated lines (service tag, BIC, recipient, IBAN, amount, remittance…). EUR-only, recipient name required. Once you know the spec, generating them is deterministic — no API, no key, no rounding surprises. A lot of "QR code generator" tools just wrap a remote API; this one computes everything locally, which is what makes the privacy claim real.

2. IBAN validation is a tiny party trick. mod-97: move the first 4 chars to the end, turn letters into numbers, and the whole thing mod 97 must equal 1. ~10 lines, catches most typos before a QR is ever drawn.

3. Privacy is an architecture, not a checkbox. OCR uses tesseract.js and QR decoding uses jsQR, both lazy-loaded in the browser. The image never leaves the device. I could only honestly write "your image never leaves your device" because there is literally no backend.

The MCP part (and a payment-safety gotcha)

It's also an MCP server, so in an AI client you can hand it an invoice (PDF or photo) and the model reads the IBAN/amount/reference and calls qr_payment. The instructions force a read-back step: the model echoes the extracted fields and asks you to verify before showing the QR — because a misread digit is real money gone.

Here's the non-obvious part I burned an afternoon on. The tool returns the QR as an MCP image content block:

content: [
  { type: 'image', data: base64png, mimeType: 'image/png' },
  { type: 'text',  text: JSON.stringify(result) },
]

In Claude Desktop, that image is given to the model as rendered pixels — which the model cannot re-export. So when I told it "show the user the QR as a file," it couldn't access the bytes… and helpfully regenerated the QR from the payload using its own library. For a payment QR that's dangerous: the model just became the source of truth, and a single mistyped character would silently corrupt the transfer.

Two fixes:

Never regenerate — and if the model has no choice, make it qr_read its own image and diff the payload character-for-character before showing it.
Return the PNG as base64 text too (qr_png_base64), so the model can write the exact bytes to a file with zero re-encoding.

Lesson for anyone building image-returning MCP tools: the rendered image block is for the human; if you also want the model to do something with the bytes, hand them over as text.

Try it

https://qr.cz-agents.dev — type an IBAN, or drop a screenshot. It's free and there's nothing to sign up for. I'd love feedback on EPC/GiroCode edge cases (BICs, structured vs unstructured remittance) — that's where the spec gets fiddly.

Building MCP servers for a country that isn't in the dataset (Czech gov APIs)

Martin Havel — Thu, 16 Apr 2026 15:57:32 +0000

Abstract

In December 2025, Anthropic donated the Model Context Protocol to the Linux Foundation. MCP is now a vendor-neutral standard — OpenAI, Block, and dozens of IDEs ship with it. The registry has ~300 servers. Most of them are for English-first ecosystems: GitHub, Slack, Linear, Notion.

Nobody had written an MCP server for Czech government or business data. So I spent an evening doing it. Two servers live, published to npm and the official registry. This is what I learned about adapting MCP to a locale the tooling wasn't designed for.

TL;DR

Source: github.com/martinhavel/cz-agents-mcp
Landing: cz-agents.dev
npm: @czagents/ares, @czagents/cnb
Registry: dev.cz-agents/ares, dev.cz-agents/cnb

1. The context problem

If you ask Claude about GitHub, it knows what GitHub is. It ships with an MCP server for it. Same for Postgres, Puppeteer, Stripe, Slack.

If you ask Claude about ARES (the Czech Business Register), it doesn't know. It's gov data for 10M people. The API is public and documented. But there's no MCP adapter. So every time you want your Czech tax assistant to pre-fill a company address from an IČO, you have to either:

Write a one-off REST wrapper in your agent code.
Tell Claude "call GET https://ares.gov.cz/... with these params, then parse the JSON."

Neither scales past one agent. MCP solves this for English-speaking SaaS — it should solve it for everyone else too.

2. The Czech Business ID gotcha (MOD11)

Every Czech company has an IČO — 8-digit identifier. But not every 8-digit number is valid. The last digit is a MOD11 checksum:

export function isValidIco(input: string | number): boolean {
  const ico = String(input).padStart(8, '0');
  const digits = ico.split('').map(Number);
  let sum = 0;
  for (let i = 0; i < 7; i++) sum += digits[i] * (8 - i);
  const rem = sum % 11;
  const expected = rem === 0 ? 1 : rem === 1 ? 0 : 11 - rem;
  return expected === digits[7];
}

This is the kind of knowledge that's obvious if you've built Czech software and invisible otherwise. An MCP server that accepts IČO input must validate before hitting the upstream API — otherwise every typo wastes a round-trip and risks getting your origin IP blacklisted.

This is reason #1 an MCP wrapper has real value over "tell the LLM the REST path": it encodes domain knowledge the LLM won't know.

3. The ARES API that lies

ARES has an OpenAPI spec at https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/v3/api-docs. If you follow it to build a client, your requests will return 404.

The actual endpoints are at a different path than the spec claims. For example:

Docs say: GET /v3/ekonomicky-subjekt/{ico}
Reality: GET /ekonomicke-subjekty/{ico} (no /v3/, plural noun)

It took an hour of DevTools staring to figure out. I put the correct paths in the MCP server and cached the gotcha in repo docs. That's reason #2 — downstream consumers don't re-discover the mismatch.

4. DNS authentication for the MCP registry

The MCP registry (registry.modelcontextprotocol.io) supports four auth methods: GitHub interactive, GitHub OIDC, DNS proof, HTTP proof. For a custom namespace like dev.cz-agents/* (reverse-DNS, so the domain name claims ownership), DNS is cleanest.

How it works:

Generate Ed25519 keypair: openssl genpkey -algorithm ED25519 -out private.pem
Add TXT record at the root domain (not _mcp. as some docs suggest):

   cz-agents.dev.  TXT  "v=MCPv1; k=ed25519; p=<base64 public key>"

mcp-publisher login dns --domain cz-agents.dev --private-key <hex> — the CLI signs a challenge, the registry fetches the TXT and verifies.
mcp-publisher publish packages/ares/server.json

Two things caught me off-guard:

The public key must be base64, not hex (documentation was ambiguous).
The registry's DNS resolver has a negative cache of ~60 seconds. If you tried to log in before adding the TXT, you'll get no such host for a minute even after the record propagates.

5. Rate limiting against yourself

The ARES servers run on infrastructure paid for by Czech taxpayers. Hammering them from an AI agent is rude and eventually gets your IP blacklisted.

I built two layers:

Application rate limit per client IP (60 req/min, token bucket in memory), reading CF-Connecting-IP when behind Cloudflare. Returns 429 + Retry-After header.
Response cache — ARES company data changes maybe monthly. I cache by IČO for 1 hour. For a batch of 100 agents asking about the same invoice, that's 1 upstream call instead of 100.

If you're building an MCP server over a public API, these aren't optional. Your origin IP is a shared resource.

6. The scope problem

ARES is well-documented. But once you step beyond it, Czech gov APIs range from "poorly documented but functional" to "only SOAP, service has been down for 18 months" to "the data is behind an Angular SPA with no backend API".

I spent 15 minutes probing ISIR (insolvency register) and found: REST endpoints return 404, SOAP is unreachable, the "open data portal" is a React app that fetches its own JSON via undocumented URLs. I dropped it from v1.

Lesson for other locales: start with the APIs that have OpenAPI specs and no auth. Business registries, currency rates, postal codes. Save the complicated ones for v2 when you have community pressure and can involve users in testing.

7. What's live

@czagents/ares — 9 tools: lookup_by_ico, search_companies, search_by_address, search_by_nace, get_statutaries, validate_dic, check_vat_payer, get_bank_accounts, get_history.
@czagents/cnb — 3 tools: get_rates, convert, get_rate.
Streamable HTTP at https://ares.cz-agents.dev/mcp and https://cnb.cz-agents.dev/mcp.
Rate-limited, cached, MIT licensed.

8. Why bother — the real answer

I build two Czech SaaS products: Kniha Jízd (mileage logbook) and Šiml (tax assistant). Both need ARES lookups daily — "fill in the address of this company by its IČO" was hundreds of lines of custom integration code per product.

Now it's one config line in claude_desktop_config.json or a three-line fetch from my own SDK. The open-source version is a side-effect of building my own tooling for my own products. That's the best reason to open source: you were going to write it anyway.

If you're building software for a non-English-first locale, I'd love to see a /fr-agents, /de-agents, /jp-agents drop in the coming months. The pattern is portable.

Update — 2026-04-27, eleven days later

Quick technical update on what shipped since this article, in case anyone
is looking for the same scaffolding for their own locale:

Five packages live, not two: @czagents/{ares, cnb, sanctions, isir, dd}. The new ones cover EU FSF + OFAC SDN sanctions screening, an ISIR insolvency-register client built on the Czech Justice Department's SOAP service, and a due-diligence aggregator that cross-references all three plus walks the statutory chain (UBO-style).
Glama scored it A/A/A (quality / security / license). Free third-party validation that costs nothing if you ship clean code with a real LICENSE, pinned deps, and proper tool annotations. Worth doing for any MCP server.
Submitted to Anthropic Connectors Directory. Pending review. The submission process itself was a useful audit — they ask for tool annotations (readOnlyHint, openWorldHint, titles), privacy policy, GDPR legal basis, public terms. All things any production MCP server should have anyway.
One subtle infra gotcha worth flagging for other MCP server authors: Anthropic's reachability prober uses python-httpx with Accept: */*. The MCP TypeScript SDK does a strict string-match on the Accept header and returns 406 Not Acceptable, which Claude.ai surfaces as the cryptic "Couldn't reach the MCP server". Fix: pre-handler that rewrites Accept: */* → Accept: application/json, text/event-stream on both req.headers AND req.rawHeaders (the SDK uses hono/node-server which reads from rawHeaders). Cost me three hours of debugging — sharing so nobody else does the same.

The pattern from the original post — adapt MCP to a non-English locale,
ship small, let the registry do the discovery — held up. Whether anyone
finds it useful in production is a separate question, and one I don't
have data on yet.

Questions, feedback, PRs welcome at github.com/martinhavel/cz-agents-mcp. If your country has similar public registries and you want a hand designing the namespace, ping me.