DEV Community: Martin Havel

x402 processed 169M payments. On my eight MCP servers: zero. Only the scouts arrived.

Martin Havel — Sun, 19 Jul 2026 12:34:21 +0000

Part of a series on building cz-agents → under the hood.

Where we left off

In June, I compared the three camps of agentic payments here—x402, card tokens, and banks—and argued that x402 will take machine-to-machine micropayments, while cards and banks split the rest. I won't repeat the basics of the protocol, how the 402 status code works, or why cards don't add up economically on tiny amounts; anyone who needs a refresher will find it in that article.

This piece is about something else. A few weeks have passed; the numbers and the big-player backing have both jumped by an order of magnitude, and for the first time, I can compare those figures against what I actually see in my own logs. The gap between the two is the entire point of what follows.

The numbers are hard to miss

I'll start with what speaks for x402, because that's the more honest approach. According to aggregate Chainalysis data, the protocol has processed over 169 million payments so far, between roughly 590,000 buyers and 100,000 sellers. That's no longer a conference demo.

More interesting than the volume is the structural shift. The share of transactions above one dollar rose from 49% in early 2025 to roughly 95% in early 2026. In other words: x402 is ceasing to be a toy for micro-cents and is starting to handle amounts that actually show up on the books. Anyone who wrote the protocol off as a curiosity for paying fractions of a cent per API query is looking at an old snapshot.

Above all, a lineup has assembled that is hard to dismiss as crypto-bubble enthusiasts:

Stripe launched x402 support on February 10, 2026, in the preview of its Machine Payments product (USDC on the Base network).
Ripple added native x402 to the XRP Ledger on June 21, 2026.
AWS built x402 into Bedrock AgentCore Payments—together with Coinbase and Stripe—and also lets you monetize agent traffic on CloudFront and WAF. Sites behind Amazon's edge can charge agents right at the edge, without touching their core application.
Google is a founding participant in the x402 Foundation and built the protocol into its Agent Payments Protocol (AP2).
The x402 Foundation itself, founded in September 2025 by Coinbase and Cloudflare, moved to formal governance under the Linux Foundation on April 2, 2026. With this move, the protocol stopped being the property of a single exchange.

When Stripe, Amazon, Google, and Ripple all adopt the same standard in a single year, and the foundation hands it over to neutral governance, that's usually a signal that infrastructure is being built—not that theater is being staged. At least, that's how it looks from the outside.

What I see on my own servers: nothing

I run eight public MCP servers—the Czech business register, due diligence, sanctions lists, insolvency, central-bank FX rates, VAT, European company registers, and real-estate data—plus one paid server. They're exactly the kind of services discussed in the context of the agentic economy: machine-readable data, a small query, a clearly bounded answer, and no reason a human should have to fill out a form to pay for it.

Total agentic payments processed across all of them: zero.

Before anyone turns that into a headline, I should state the uncomfortable truth upfront—otherwise, you'd figure it out yourself and be right: my servers don't accept x402. They have no wallets, they don't return a 402 status with payment terms, and they can't verify signed stablecoin payments. Money reaches me via Stripe subscriptions and API keys with tier limits. An agent wanting to pay me for a single query has no way to do so.

So zero payments isn't evidence against x402. It's evidence about me. Concluding "see, nobody uses this protocol" would be a cheap trick: building a straw man out of my own inaction just to knock it down. The absence of payments on a server that can't accept them says nothing about demand.

The interesting part is something else—something that is in the logs.

The only things arriving from the x402 economy are the scouts

My access logs regularly show a probe identifying itself as 402.ad-mcp-probe. It belongs to the 402.ad catalog, which describes itself as a search engine for the agentic economy. It didn't just hit one server; it systematically went through all nine. And it's not alone—my logs show a whole fleet of similar indexing services mapping out who can do what.

The logic behind that catalog is the substantive part. It indexes two categories: "MCP server" and "x402 API." When its probe hits an endpoint that returns a free response, it files it under the first bucket. If it hits an endpoint returning a 402 or 401, it marks it as paid, and potentially x402-compatible. Its own programmatic interface for registering a new service costs 0.10 USDC, payable via x402. The catalog of the agentic economy charges for a listing using the protocol of the agentic economy. It's a service that doesn't just index the protocol; it uses it.

Boiled down to the single sentence this piece exists for: the only things that have actually reached me from the entire x402 economy are probes checking whether I can accept a payment. Not agents with wallets. Not demand. Just mappers.

Infrastructure gets built first. Catalogs take inventory of who can accept payments before there is any paying traffic. That's an observation, not a complaint—but it can be read two ways, and honesty demands looking at both.

Two readings of the same thing

First reading: rails before the train. That's how every payment network comes to be. Before anyone can pay by card, a terminal has to exist; before a terminal exists, someone has to walk from shop to shop to find out who wants one. The mapping phase always precedes demand, and the numbers above suggest the train is already running somewhere—just not on my rails. If this were purely hype, Stripe wouldn't have shipped a product, AWS wouldn't have put it in the CloudFront billing layer, and the Linux Foundation wouldn't have taken it under its wing.

Second reading: rails for a train that will never arrive. That's also how every tech bubble starts. Enthusiasts build infrastructure, catalogs index it, the ecosystem congratulates itself on its growth—and the end customer never arrives, because their problem was solvable in another, cheaper way. Probes from a catalog aren't demand. They are someone else's sunk cost on a bet that demand will materialize.

I don't know which of these two readings is correct, and I won't pretend to. But I do know what signals to look for, which is more useful:

Will a probe arrive asking about price, rather than just existence? The difference between "I have you in the catalog" and "how much does this query cost?" is the difference between a map and a market.
Will an agent show up in the logs that receives a 401 and actually tries to pay? Today, agents just leave upon refusal. When one of them finally tries to resolve a refusal with a payment, the nature of the traffic will have changed.
Will a human customer ask? The strongest signal isn't machine-made. When someone building an agent writes to me wanting to pay per unit—because a subscription doesn't fit their needs—the debate is over.

I haven't seen a single one of those three signals yet. That's a fact, not an opinion—and it's the only thing I can honestly claim about x402 demand based on my own data.

So should I turn x402 on?

This is the question every API operator asks themselves after reading the numbers above. I'll work through it using my own case, because there is no universal answer.

For. The barrier for an agent is zero: no registration, no key, no waiting for a human to approve access. My data is exactly the kind of small query worth paying for per unit—one company check, one FX rate, one sanctions scan. With the ecosystem now being pushed by Stripe, AWS, and Google, the integration path will keep getting shorter. What takes a week of work today could be a library and three lines of config a year from now.

Against. My paying customers are people with subscriptions, not agents with wallets. Billing in USDC means, in the Czech context, an entirely new chapter of tax and accounting work—overhead I'd be taking on for demand that no one has actually expressed yet. Furthermore, every additional payment path is one more thing that can break: more code, a larger attack surface, and more things to monitor in a system where I'm already tracking tiers, quotas, and per-query limits.

Decision: I'm not turning it on—but I'll set up a gauge. This isn't because I don't believe in x402. I believe in it just as much as I did in June: it will eventually take over machine-to-machine micropayments. I'm not turning it on because between "the protocol is growing" and "someone will buy my specific data per unit" lies a massive assumption I have no data to back up. Turning x402 on today would mean building a terminal based on someone else's numbers, hoping the mappers who visit me will one day bring a buyer with them.

What I'll do instead is cheaper and more informative: I'll measure the three signals from the previous section. I already have traffic classification on my servers. I can tell a catalog probe from a real tool call—which, incidentally, is the distinction where a lot of confident adoption numbers in this field fall apart. When the first agent wanting to pay lands in my logs, or the first human asks to pay per unit, it'll be a bet backed by evidence, not just a trend. Until then, waiting is my cheapest option. It's also reversible, which is more than you can say for a half-built payment layer.

What I take from this

The answer to "is x402 exploding?" is, by every available metric, yes. My logs don't contradict that, because my logs know nothing about it. That's the honest version. Zero payments on a server with no payment gateway is not a data point about the protocol; it's a data point about my prioritization.

What is a data point about the protocol is the probe. Someone is spending money to map out who can accept machine payments—and doing so before they have anyone to sell the map to. That's either the harbinger of something massive, or an expensive inventory of a market that will never form. Anyone who tells you today, with absolute certainty, which of the two it is, is selling you something.

Oddly, that uncertainty doesn't make me nervous. It means I don't have to decide right now—I just need to know what to watch. When demand appears, it will show up in my logs before I read about it in a press release. That's the only edge I have over the big players: I don't have to place my bets in advance.

Source for x402 adoption figures: Chainalysis — x402 agentic payments adoption. Traffic data on my own servers comes from access log classification across my portfolio of MCP servers.

Correction, 26 July 2026. A reader here pointed out that the second signal above is mis-specified, and they are right. A 401 carries no price and no inline way to pay, so an agent that receives one has nothing to answer with money — it can only guess. The signal that means something is a 402 carrying terms, followed by an actual payment. I have left the original wording rather than quietly rewriting it, because the mistake is the interesting part: I was watching the thermometer that was easiest to read instead of the one attached to the question.

I gave myself an AI advisory board — three models argue, I decide

Martin Havel — Mon, 22 Jun 2026 13:16:36 +0000

Most "use AI for your work" advice stops at ask one model, take the answer. That's a single perspective delivered in a confident voice — and confidence is exactly what you shouldn't trust on a decision that matters. So I stopped asking one model anything important. I built a small advisory board instead: three models, three roles, run in parallel, and I'm the one who decides at the end.

Here's the setup and what it actually buys you.

The harness

I drive everything from Claude Code as the orchestrator. A single skill — I call it triad — takes a brief and fans it out to three workers, each with a fixed role:

The business analyst (Gemini, via the gemini-cli bridge) — market, demand, positioning, "would anyone care."
The architect (Opus) — structure, trade-offs, failure modes, "what breaks at scale."
The builder (Codex, in the background) — the concrete implementation pass, "what would this actually cost to ship."

They don't see each other's output. That's the whole point: I want three independent reads, not a consensus that formed because one model anchored the others. The orchestrator collects all three, then does a synthesis pass that lays their reasoning side by side and flags where they disagree.

Why parallel and blind matters

The value isn't in the agreement. When all three land in the same place, fine — low-information. The signal is in the disagreement: the architect says "this couples two systems you'll regret," the analyst says "nobody asked for this," the builder says "three days, not three hours." Three different failure modes I'd never have surfaced by iterating with one model in a single thread, where each follow-up just reinforces the first frame.

A board meeting that saved me six months

A real one, lightly abstracted: an automated energy-arbitrage bot I was genuinely excited about — the kind of project you can already picture running. I briefed the panel half-expecting a green light. Instead they took it apart from three sides: the analyst found the demand wasn't really there, the architect showed the edge evaporated once you priced in the moving parts, and the builder put a number on the maintenance that would have quietly eaten my weekends for a year. None of them forbade anything — they just laid the decision out so clearly it made itself. I shelved it, and never spent the six months of development I'd otherwise have sunk into learning that the hard way.

What lands on my desk

The synthesis isn't a verdict — it's the three reads stacked up with the seams showing:

Project X — synthesis

Analyst: market is thinner than I assumed — maybe a few hundred users, not thousands.

Architect: turns a stateless tool into a service; you now own uptime.

Builder: ~10 days, not the weekend I'd pictured.

Where they split: analyst sees low value, builder says it's cheap to try — so it's a small experiment, not a bet.

I read that and decide. The disagreement line is the part I'm actually paying for.

Gotchas I hit

False consensus. Models trained on overlapping data agree for the wrong reasons. If you only count votes, you'll mistake correlation for confirmation. Read the reasoning, not the verdict.
Sycophancy leaks in through the brief. If your prompt smuggles the answer you want, all three will hand it back. Keep the brief neutral; let them fight.
It's expensive and slow. Minutes and three model calls, not a one-second answer. This is for decisions, not lookups — I don't run a triad to rename a variable.
Synthesis is where you can cheat yourself. The merge step is tempting to skim. The disagreements are the product; if you collapse them too early you've just paid three times for one opinion.

The one rule that makes it safe

The board advises. It researches, stress-tests, and prepares the ground from several angles. It does not decide. The decision — and the accountability for it — is always mine, a human's. That's not a disclaimer; it's the operating principle. An LLM ensemble is a fantastic way to see a problem from more sides than you could alone. It is a terrible thing to outsource judgment to. Keep the human as the synthesizer and the decider, and the whole pattern gets stronger, not weaker.

I've been running this for about six months now, and often — it's become my default for anything that would cost real time to get wrong.

If you take one thing: don't ask one model and trust the confident voice. Make a few of them argue, read where they break apart, and then you decide.

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.