DEV Community: Sidney da S. P. Bissoli

Your MCP server changed. Its version didn't. Here's how to catch it.

Sidney da S. P. Bissoli — Wed, 07 Oct 2026 13:38:50 +0000

A version number is a promise: nothing a client depends on changed without me saying so. For MCP servers, almost nothing checks that promise.

The copy of a server in the MCP Registry carries a name, a version, the packages and the remotes. It carries no surface: no tools, no instructions, nothing about what answers without a token. So anyone comparing the registry with the live server can compare exactly one thing, the version. That comparison is only worth something if every surface change bumps the version.

This post is about turning that "if" into a failing test, and then about what happened when I ran the test backwards over the whole history of my seven servers: 142 published versions.

Where this came from

It started in the comments of my previous post, in a thread with @yahhi. The registry listing and the live worklore server both said 0.1.0, so a version diff passed cleanly. But, as @yahhi found, the server had moved on: tools/list now answered without a token, and the auth rules had moved into the instructions. The drift was one level deeper than the version.

Next came a working check, and a replay of the surface from the day of the listing against the current code. The registry said 0.1.0 for a server with four read-only tools. The server behind that number had six, two of which write on the user's behalf.

I said I'd build the same thing for my servers. It's now live on all seven, and packaged as @sbissoli/mcp-surface.

1. Lock what the client sees, not what the code says

The lock file, surface.lock.json, sits at the root of each server, next to package.json. It has two sections. Each stores the version it was locked under and a sha256 of its content.

Declared surface: the initialize result (instructions and capabilities included, serverInfo without the version), plus tools/list, resources/list, resources/templates/list and prompts/list. Keys are sorted and lists are ordered by name or URI, so the hash only moves when the surface does. A method the server doesn't serve is recorded as null, not []: "no prompts" and "prompts/list isn't served" are different surfaces.
No-token behaviour: which methods answer without a credential, on every MCP route, with the API key unset and set. No listing shows this, and it's exactly what had drifted in that server.

The declared surface is captured from the server factory in-process. The no-token section is measured at the HTTP edge, by calling the Worker's fetch with and without the key.

2. Make the version bump the only way out

The rule is short:

measured ≠ locked and the version is the same → the test fails;
the version changed → the test fails and asks you to re-lock.

The script that rewrites the lock follows the same rule: it refuses to lock a new surface under the old version. You can't "fix" a red test by regenerating the lock. You bump the version, re-lock, and commit the lock with the bump:

npm version minor --no-git-tag-version
npm run surface:lock   # build + run the surface tests in write mode

The deploy runs npm test before wrangler, and the npm publish runs it before npm publish. So a surface change without a version change can't be deployed or published.

One side effect, and it's on purpose: an SDK upgrade that changes capabilities also turns the lock red. The client sees a different surface, so the version should say so.

3. Green tests prove the code; a post-deploy check proves what's served

Tests run against the code in the repository. The client talks to whatever is actually deployed. Usually those are the same thing. Wrangler configs, build steps, environment variables and caches are where they stop being the same.

So every deploy now ends with one more step that queries the live endpoint and compares it with the lock:

npx mcp-surface verificar https://<host>/mcp --tool <a tool that needs no network>

If what's being served isn't what was locked, the deploy job goes red after the fact, which is still much better than never.

4. The lock only protects you from now on, so replay the history

A lock written today says nothing about the versions that came before it. For those there's a replay:

npx mcp-surface replay --url https://<host>/mcp

For every version published on npm, it installs the package in a temporary directory (--ignore-scripts), starts it over stdio and captures the surface with the same normalisation the lock uses. Then it compares each version with the previous one, lists every removal that didn't come with a major bump, and checks the live endpoint against the surface of the version its /status reports. The output is a Markdown table and a JSON file in baselines/, committed to the repo.

Across the seven servers that came to 142 versions. In all seven, the live server matches the version it reports. It also found three things I didn't know.

5. Two releases that don't even start

Two old releases of my Senate server, 1.1.0 and 1.1.2, crash on startup:

Error: Dynamic require of "events" is not supported

The esbuild bundle emitted ESM that still contained a CommonJS require for a Node built-in. Nobody had noticed, me included, because nobody installs a two-version-old release on purpose. But npm would have offered both as valid versions indefinitely. Any version diff would have called them fine forever, because their version numbers are perfectly well-formed. They're deprecated now.

The lesson: "the version string is right" and "the version runs" are different claims, and only one of them shows up in a registry.

6. A minor release that removed six tools

My medical terminology server went from 1.0.2 to 1.1.x and six SNOMED CT tools disappeared from the default surface. They moved behind a licensing flag, off by default.

The CHANGELOG for that release even called it "technically breaking". It shipped as a minor anyway. There was a reason, since SNOMED access depends on a licence the user has to hold. But the client that was calling snomed_search yesterday doesn't read my reasoning. It gets "unknown tool".

The replay lists cases like this without judging them. Some removals have a good reason, and the CHANGELOG is where that reason lives. What matters is that the list exists, so the decision is made on purpose rather than discovered later by a user.

7. The replay was wrong once, too

The first version of the replay flagged ilo-mcp-server 0.5.0 → 0.6.0, where a parameter became required, as a breaking change outside a major release. But under semver, 0.x is allowed to break in a minor. The line of compatibility in 0.x is the minor, not the major.

The rule is fixed now: in 0.x, breaks are compared within the same minor. I mention it because a tool that reports drift has to earn its alarms. One false alarm on day one teaches people to ignore the next real one.

8. Check the probe before you write the lock

This is the one I'd most like other people to avoid.

In one server (sih-br-mcp) the MCP backend sits behind an edge proxy, so the no-token test can't call the real handler in-process. My first test double for that backend answered result to every method. The lock was written from it, and it faithfully recorded "prompts/list answers" for a server that has no prompts.

All the tests passed, because the tests were checking the lock against the same lying double. The post-deploy check against the live endpoint is what caught it.

The fix has two parts. A double that answers everything is not a double of your server, so where the real handler can run in-process, run it. And the probe's sanity checks (a method that must answer, a method that must not) now run before anything is written to the lock, not after. A lock written from a broken probe is worse than no lock, because it makes a wrong surface look verified.

What I would do first, next time

Lock the surface next to the version from the first release: initialize, the four lists, and which methods answer without a token.
Make the lock script refuse to rewrite under the old version. Otherwise the red test just becomes a ritual.
Check the live endpoint after every deploy. Green tests prove the code; only this proves what's served.
Run the replay once over your whole history. It's cheap, it's one command, and the first run is the one that finds things.
Prove the probe can say "no" before you trust anything it says "yes" to.

The package is MIT: @sbissoli/mcp-surface, source in mcp-br-commons. Fair warning: the API and CLI verbs are in Portuguese (travar = lock, verificar = verify), and the roadmap follows my own servers' needs.

Thanks to @yahhi for the thread that started all this. There is also a write-up of the other side of it, in Russian, on Habr. One comment thread changed how eight servers ship.

Building an MCP server for financial data: lessons learned

Sidney da S. P. Bissoli — Sat, 26 Sep 2026 20:34:12 +0000

Originally published on Medium.

I maintain bcb-br-mcp, an open-source MCP server that gives AI agents the Brazilian Central Bank's public data: the SGS time series (Selic, IPCA, exchange rates, GDP, credit), the Focus market-expectations survey and the PTAX reference rates. It runs over stdio from npm and over Streamable HTTP on Cloudflare Workers, has 17 tools, 388 tests, and serves a couple of thousand npm downloads a month plus a hosted endpoint.

None of the lessons below are about the MCP protocol itself. The protocol was the easy part. The hard parts were the data source, the two transports, and the difference between a response that looks right and one that is right. Here they are, roughly in the order they cost me.

1. Your source will lie to you with HTTP 200

The single most expensive class of bug: the upstream API answers a bad request with a success code.

The SGS endpoint, asked for a series code that does not exist, returns HTTP 200 with an HTML page ("invalid request"), after about 30 seconds. A valid series answers in 0.2 to 0.4 seconds. So the naive server waited half a minute and then tried to parse HTML as JSON, and the error message blamed the source for being down.

Worse: the same HTML page occasionally comes back for a series that does exist. I measured it on series 432, the Selic target: 3 HTML pages out of 9 calls within a few minutes, then 20 consecutive good JSON answers. My first fix treated the page as a verdict ("this series does not exist") and raised without retrying. That meant a hiccup at the source made the server assert that the Selic target rate did not exist.

The page proves only that that attempt brought no data. The server now resolves the suspicion by repetition: a code that does not exist fails every attempt; a good series comes back on the next one. And small requests (ultimos/N, at most 20 observations) get their own 6-second budget, because they can never be a legitimate long query — which cuts the 30-second silence without touching the long windows.

Lesson: classify errors by the shape of the body, not by the status code, and never let a single anomalous response become a permanent verdict.

2. "Last minus first" is wrong for half of the interesting series

Price indexes — IPCA, IGP-M, INPC — are published as monthly rates, not levels. Compute the variation of IPCA over 2024 as (last − first) / first and you get +23.81%. The real accumulated inflation was 4.83%. For the IGP-M in 2023 the naive formula gave +252.38% for an index that actually fell 3.18%.

Nobody reported this. A paid evaluation run, where a real model picked tools for 44 Portuguese prompts, caught it by accident, because one answer was absurd enough to notice.

The fix is a per-series decision (level vs chained rate vs already accumulated), and it is partial by construction: some series are recognised by the unit the open-data portal publishes, some by their curated name, some by an explicit list of period rates. The index heads (433, 189…) have no unit at all in the source; only the name identifies them. A code outside the catalogue is treated as a level, and the contract says so.

Lesson: a numeric tool has domain semantics. If your server computes anything, the computation needs to know what kind of number it is holding, and the response must say which convention it used.

3. Ordering is not a property of the endpoint

ultimos/N — "the last N observations" — returns 22 of the 169 curated series newest-first and the other 147 oldest-first. The direction is not deducible from the code or the family: series 4390 comes reversed, series 433 does not. Meanwhile, the date-window endpoint returned ascending order in 151 of 151 series.

The visible symptom was a variation published with the wrong sign: −7.40% for a period in which the series rose 8.00%.

Every observation that enters the server now passes through one sort-by-date function. Nothing else reads data[0] as "the oldest".

Lesson: measure invariants you assume, across the whole catalogue, not on the three series you tested with.

4. Two transports, one registry — or you will ship two products

At the start the server had two independent surfaces: the stdio entry derived JSON Schemas from zod through the SDK, and the Cloudflare Worker re-implemented JSON-RPC by hand with its own copy of the schemas. They had genuinely diverged:

	stdio (npm)	hosted (Worker)
version in production	1.3.5	1.3.1
tool description length	~1,200 chars	~100 chars
`default`, `minimum`, `maximum`, `minItems`, `additionalProperties`	present	missing
resource names	one set	a different set

The agent-readable descriptions I had spent a release writing never reached the hosted endpoint, because there was no deploy pipeline for the Worker. And the HTTP client got a weaker contract than the stdio client, because the JSON Schema was maintained twice.

The fix was structural: one registerAll(server) function is the only place that projects tools, resources and prompts onto an McpServer; stdio calls it once, the Worker calls it per request. The JSON Schemas are the published surface and go on the wire verbatim. A normalised dump of tools/list + resources + prompts is committed as a baseline, and the CI compares the surface before and after every change; the hosted endpoint is deployed on every push, with a production smoke test at the end.

Lesson: if two entry points can describe the same tool differently, one of them is lying to some client right now. Make a single registry and test that the two transports are byte-identical.

5. The runtime will veto your validator

The obvious JSON Schema validator for TypeScript is ajv. Ajv compiles schemas with new Function. Cloudflare Workers forbid new Function — and the failure mode is not a nice error on the offending tool; it is HTTP 500 on the whole /mcp route.

The server uses a non-compiling validator on both runtimes on purpose, so that stdio and hosted validate identically.

Lesson: pick the validator for the most restrictive runtime you deploy to, and use the same one everywhere.

6. A field that can be `null` must say so, or a validating client rejects everything

The tools return null deliberately where the source does not publish a field — null is the information that there is no data, and the normalisation never omits keys. But an outputSchema that declares "type": "string" while the server emits null violates the spec, and a client that validates (the MCP Inspector does) rejects the entire response, not the one field.

Runtime output validation in the SDK is permissive by design, so nothing at runtime catches this. I added a test that validates the structuredContent of every tool against its own announced outputSchema, with the same validator the server uses on input, and made the null-producing paths the test cases.

Closely related SDK rule: any tool that declares outputSchema must return structuredContent on every success; the check runs before any validator and cannot be disabled. All handlers go through one structuredResult() helper, so this can only be forgotten in one place.

Lesson: the output schema is a promise to a stranger's validator. Test the promise in CI; do not rely on the runtime.

7. Provenance is a contract, and the timestamp is the hard part

Every successful response carries a provenance block: source, series, period, the canonical URL that reproduces the query, the licence (ODbL), and retrieved_at.

The tempting implementation of retrieved_at is new Date() at response time. That is a false statement whenever the answer came from a cache: a search served from the 24-hour metadata cache reports the instant of the original fetch, which may be yesterday — and that is the date with legal weight, because it is when the extraction actually happened. The server collects the real instant at the single network call site through AsyncLocalStorage, aggregates by taking the oldest instant across the accesses that built the answer, and sets served_from_cache only when everything came from cache.

The second subtlety: the same channel that carries the source's numbers verbatim must mark anything the server computed — a variation, a correlation, a deflated series — as derived, with the convention used. A provenance block can match the schema and still lie; there is a dedicated test for the block's truthfulness, with a coverage assertion so that a new tool without a provenance test fails the suite.

Lesson: provenance is not metadata decoration. It is a claim about when and from where each number came, and it needs its own tests.

8. Latency is queue depth, not request count

Daily series are capped at 10 years per request (HTTP 406 above that), and a legal 10-year window takes 10–20 seconds at the source, with a server-side cut around 30 seconds that returns — you guessed it — 200 with HTML. The Worker has a 10-second budget. So the server slices windows into 3-year chunks (~2.6 s each).

Then a comparison of two daily series over 10 years still took 10.7 s, and five series took 10.4 s: the problem was not the number of requests but the depth of the queue per series. Splitting a budget of 10 concurrent requests across the series brought the worst case to ~8.8 s.

One measurement rule saved me from fooling myself here: always measure on a window never requested before. The source serves repeats from cache, and an already-requested window measures 600 ms where the cold one measures 10 s.

9. Hand-curated catalogues rot; verify them against the source

The server ships a curated catalogue of 135 series so that agents can find "IPCA" or "household credit" without knowing a code. When I finally verified every entry against the source, about half of the earlier errors had come from names edited by hand: two series swapped, individuals and companies inverted in a pair of credit series, a block of household-debt series sold as Focus expectations.

Each entry now records where its name came from — transcribed from the portal's dataset (82) or measured (53: no dataset anywhere, name inherited, only periodicity and magnitude checked) — and there is a rule not to "improve" a transcribed name by hand.

The obvious shortcut — validate a code against the open-data catalogue before hitting the network — is wrong too: the catalogue lists 4,261 datasets but 10 of 20 well-known valid codes are absent from it, including 433 (IPCA). Pre-validating would have refused good series.

Lesson: a catalogue is a claim about the source. Store the evidence for each claim, and never let a secondary index veto the primary one.

10. Telemetry that counts by status code is blind to the errors you most need

The Worker keeps usage counters. Reconciliation between the tool-call hook and the HTTP layer was by status: if (status < 400) continue, on the assumption that 200 implies the hook recorded the call. But a schema refusal is answered by the validator before the handler, inside an HTTP 200 — so nobody recorded it and the continue closed the only other door. Calls with malformed arguments were counted neither as calls nor as errors. Measured in production: schema refusal, unknown tool (−32602) and unknown method (−32601) all arrive as HTTP 200.

The fix reconciles by name against the hook's receipt and reads the outcome from the JSON-RPC envelope matched by id. The same defect existed in a sibling server, where it was fixed first.

Lesson: in MCP, protocol-level failures live inside 200s. Instrument the envelope, not the transport.

11. Directory listings drift too

Every directory that lists your server keeps its own copy of your manifest. Mine on one marketplace sat at 1.11.0 while npm was at 1.14.1, with descriptions and schemas from before a vocabulary change — because the manifest file in the repo was not tied to anything. Now a test compares the committed manifest with the live tools/list, resources/list and prompts/list of the real server and with the identity in package.json; a stale manifest fails before a release can happen.

What I would do first, next time

One registry, two transports, a committed surface baseline. Everything else is cheaper once the surface cannot fork.
Characterisation tests with mocked fetch for every tool, value by value, before any refactor — they were the gate for replacing the statistics engine, and produced exactly two explained differences.
An output-contract test (structured output vs announced schema) and a provenance test with coverage assertions.
A paid eval with a real model, run rarely and on purpose. It found the one bug that no unit test could have, because the bug was in what the number meant.
Measure the source across the whole catalogue — ordering, caps, timeouts, error shapes — and write the numbers into the repo where the next maintainer (often me, six weeks later) will read them before "optimising" something.

The code is MIT, the data is ODbL from the Banco Central do Brasil, and the repository's CLAUDE.md holds the full list of the sharp edges above with the dates they were measured: https://github.com/SidneyBissoli/bcb-br-mcp

How to query Brazilian economic data with AI using MCP (Selic, IPCA, exchange rates, Focus)

Sidney da S. P. Bissoli — Sat, 26 Sep 2026 15:02:22 +0000

Resumo em português: este tutorial mostra como dar a um agente de IA (Claude, Cursor, ChatGPT) acesso aos dados oficiais do Banco Central do Brasil — Selic, IPCA, câmbio, Focus e PTAX — com o servidor MCP bcb-br-mcp, em cinco minutos e sem chave de API. Cada resposta vem com proveniência: série, período, URL canônica e instante da extração.

Ask a language model "what is the Selic rate today?" and you get a number from its training data. It may be right, it may be three Copom meetings stale, and it comes with no source. This tutorial fixes that by giving the model a tool that reads the Banco Central do Brasil (BCB) directly.

What you get

bcb-br-mcp is an open-source MCP server over three public BCB APIs:

SGS time series: Selic, IPCA, exchange rates, GDP, credit, fiscal accounts and thousands more, with a curated catalogue of 135 verified series;
Focus: the weekly market-expectations survey (IPCA, Selic, GDP, exchange rate, by horizon and by Copom meeting);
PTAX: the official reference exchange rates.

17 tools, no API key, MIT licence. Data is ODbL from the BCB.

1. Connect it (pick one)

Claude.ai or Claude Desktop, by URL — add a custom connector with:

https://bcb.sidneybissoli.com/mcp

Claude Desktop or Cursor, local via npx — in claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "bcb-br": {
      "command": "npx",
      "args": ["-y", "bcb-br-mcp"]
    }
  }
}

ChatGPT Deep Research — the server also exposes the search/fetch pair that ChatGPT requires; use the same URL.

2. Ask questions

Once connected, plain language is enough. Some prompts that map cleanly onto the tools:

Prompt	Tool the agent picks
"Current Selic, IPCA and USD/BRL in one shot"	`bcb_indicadores_atuais`
"Find the series code for household credit"	`bcb_buscar_serie`
"IPCA month by month in 2025"	`bcb_serie_valores`
"How much did the IGP-M change in 2023?"	`bcb_variacao` (it accumulates monthly rates instead of subtracting endpoints)
"What does Focus expect for IPCA 2026 and 2027?"	`bcb_focus_expectativas`
"Selic expected at each Copom meeting this year"	`bcb_focus_selic`
"EUR/BRL PTAX for the whole of March 2026"	`bcb_cambio_cotacao`
"Turn this nominal revenue series into 2025 reais"	`bcb_deflacionar`
"Do Selic and the dollar move together since 2020?"	`bcb_correlacao`

3. Read the provenance block

Every successful answer carries provenance and attribution in the structured result: the source, the series and period, the canonical URL that reproduces the query, the real extraction timestamp (a cache hit reports the original fetch time, not "now"), and the licence. If the agent computed something — a variation, a correlation, a deflated series — the result is marked as derived and says which convention it used. What the BCB published is returned verbatim.

That is the difference between "the model said 10.5%" and "SGS series 432, 2026-09-17, https://api.bcb.gov.br/...".

4. Why not let the model call the REST API itself?

Because the BCB APIs have edges that produce wrong numbers silently, and a model calling fetch will hit every one of them:

unknown series codes return HTTP 200 with an HTML page, after about 30 seconds — and the same page occasionally comes back for series that exist;
daily series are capped at 10 years per request (HTTP 406), and a legal 10-year window can take 20 s, so the server slices it into 3-year chunks;
ultimos/N returns 22 of the 169 curated series newest-first and the rest oldest-first, which flipped the sign of variations;
price indexes (IPCA, IGP-M, INPC) are published as monthly rates: last-minus-first reported +23.8% for IPCA 2024 when the real accumulated figure was 4.83%;
the PTAX endpoint wants MM-DD-YYYY and returns zero rows, not an error, for ISO dates;
the Focus OData service does not paginate, does not count, and one of its resources publishes field names in lower case, alone among thirteen.

All of that is handled server-side and pinned by tests, so the agent gets numbers you can put in a report.

Seven medical terminologies, one MCP server: a practical walkthrough for clinical and research use

Sidney da S. P. Bissoli — Tue, 12 May 2026 01:55:45 +0000

If you've ever asked an LLM to "find the LOINC code for procalcitonin" or "list the active ingredients in Janumet," you've probably watched it confidently invent a code that doesn't exist. Medical terminologies are exactly the kind of structured, frequently-updated reference data that language models are bad at memorizing and good at looking up — if you give them the right tool.

medical-terminologies-mcp is a Model Context Protocol server that gives any MCP-compatible client (Claude Desktop, Claude Code, Continue, and others) unified access to seven medical terminology systems:

ICD-11 (WHO International Classification of Diseases, 11th Revision)
LOINC (Logical Observation Identifiers Names and Codes)
RxNorm (NIH normalized clinical drug names)
MeSH (NLM Medical Subject Headings)
ATC (WHO Anatomical Therapeutic Chemical, served via NLM RxClass)
CID-10 (Brazilian Portuguese translation of ICD-10, DataSUS V2008 — bundled)
SNOMED CT (Systematized Nomenclature of Medicine, optional, license required)

Twenty-six tools work out of the box with no authentication for LOINC, RxNorm, MeSH, ATC, CID-10, plus a bundled authoritative ICD-10 → ICD-11 mapping, a cross-terminology batch validator, and versioning + cross-revision diff. ICD-11 live lookup needs free WHO API credentials (a five-minute signup), bringing the default count to 31. SNOMED is gated behind an explicit feature flag and requires an IHTSDO license plus a self-hosted Snowstorm instance — more on why below.

The server also exposes 3 MCP Prompts that orchestrate tool calls into named user actions (find-medical-code, drug-info, cid10-portuguese-lookup) and 3 Resources for in-process reference content (server metadata, CID-10 chapter listing, per-terminology license disclaimers) — MCP clients render Prompts as one-click actions and read Resources by URI.

This post walks through three concrete clinical and research workflows where the server earns its place in the toolbelt.

Setup in 60 seconds

{
  "mcpServers": {
    "medical-terminologies": {
      "command": "npx",
      "args": ["-y", "medical-terminologies-mcp"],
      "env": {
        "WHO_CLIENT_ID": "your-who-id",
        "WHO_CLIENT_SECRET": "your-who-secret"
      }
    }
  }
}

Drop that into your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS), restart Claude, and 31 tools appear. WHO credentials are optional — without them the 5 ICD-11 live-lookup tools throw a clear configuration error and the other 26 work fine (including the authoritative ICD-10 → ICD-11 mapping, which uses bundled WHO data and needs no auth).

Prefer a hosted endpoint? The server runs on Cloudflare Workers at the edge — point any Streamable-HTTP MCP client at https://medical-terminologies-mcp.sidneybissoli.workers.dev/mcp and skip the local install. Also listed on Smithery, Glama, and mcpservers.org.

Use case 1: sepsis triage — finding the right LOINC for procalcitonin

A clinical scenario. An ED resident is documenting a sepsis workup and needs the LOINC code for serum procalcitonin to attach to the lab order in the EMR. They could open loinc.org, run a search, scroll through results, and copy the code. Or they could ask their LLM-powered scribe.

You: What's the LOINC code for procalcitonin in serum?

Claude (calling loinc_search):
## LOINC Search Results for "procalcitonin"
Found 23 total results (showing 10):

1. **33959-8** - Procalcitonin [Mass/volume] in Serum or Plasma
   Component: Procalcitonin | Property: MCnc | Timing: Pt | System: Ser/Plas
   Class: CHEM | Status: ACTIVE
2. **75241-0** - Procalcitonin [Mass/volume] in Body fluid
...

The LLM picks 33959-8 and proposes it. The clinician confirms or asks for details:

You: Give me the full LOINC details for 33959-8.

Claude (calling loinc_details):
# 33959-8 - Procalcitonin [Mass/volume] in Serum or Plasma

| Attribute | Value |
|-----------|-------|
| Component | Procalcitonin |
| Property  | MCnc |
| Timing    | Pt |
| System    | Ser/Plas |
| Scale Type| Qn |
| Method    | (none) |
| Class     | CHEM |
| Status    | ACTIVE |

What this replaces in practice: a 30-second context switch from EMR to a browser tab, every time a clinician needs to pin down a specific code. Multiplied across the day, across a team, that's real time.

The same workflow applies to any biomarker, vital sign, or observation: lactate (2524-7), troponin I high-sensitivity (67151-1), SpO₂ (59408-5). The tool is loinc_search for the discovery step, loinc_details for the verification step. Both are deterministic API calls against NLM Clinical Tables — the LLM doesn't memorize codes, it looks them up.

Use case 2: medication reconciliation — breaking down a combination product

A scenario familiar to any inpatient pharmacist or hospitalist: a patient is admitted on Janumet (a brand combo of sitagliptin and metformin), and the team needs to reconcile this against the formulary, check for class-level interactions, and document the active ingredients separately.

You: I need to break down Janumet for the admission med rec.
What are the active ingredients and their drug classes?

Claude (calling rxnorm_search, then rxnorm_ingredients, then atc_classify):

Step 1 — search for Janumet:
**860975** - Janumet (sitagliptin 50 MG / metformin hydrochloride 500 MG Oral Tablet)
   Type: SBD | Synonym: sitagliptin/metformin

Step 2 — get the ingredients:
| RxCUI | Name | Type |
|-------|------|------|
| 593411 | sitagliptin | Single Ingredient |
| 6809 | metformin | Single Ingredient |

Step 3 — get ATC classes for each ingredient:
For sitagliptin (593411): A10BH (Dipeptidyl-Peptidase IV Inhibitors)
For metformin (6809):     A10BA (Biguanides)
                          A10BD (Combinations of oral blood glucose lowering drugs)

Three tool calls, structured data, no hallucination risk. The LLM can compose this into a med rec note, flag that both ingredients sit in the same A10B (oral glucose-lowering) ATC bucket, and surface the ATC codes for any pharmacy system that uses ATC.

What this enables that bare LLMs don't: the chain brand → ingredients → ATC classes is a graph traversal across a real database. The model isn't recalling that sitagliptin is a DPP-4 inhibitor; it's looking it up against the same source the FDA uses.

Use case 3: evidence synthesis — building a precise PubMed search with MeSH

A scenario for a researcher running a systematic review on the impact of primary health care interventions on avoidable hospitalizations. The quality of a literature search hinges on hitting the right MeSH descriptors and qualifiers — not on free-text keyword guesswork.

You: I'm building a search strategy for a systematic review on
primary health care and avoidable hospitalizations. Help me find
the right MeSH descriptors and applicable qualifiers.

Claude (calling mesh_search):
| MeSH ID | Label |
|---------|-------|
| D011320 | Primary Health Care |
| D006297 | Health Services Accessibility |
| D004472 | Hospitalization |
| D006308 | Health Services Misuse |

You: Get me the tree position and allowed qualifiers for Primary Health Care.

Claude (calling mesh_tree, then mesh_qualifiers):
# Tree Numbers for D011320

### Health Care
- `N04.590.233.727`
- `N02.421.143.827`

# Allowed Qualifiers for D011320

| Qualifier ID | Label |
|--------------|-------|
| Q000208 | ethics |
| Q000379 | methods |
| Q000523 | organization & administration |
| Q000592 | standards |
| Q000656 | trends |
| Q000706 | statistics & numerical data |
| Q000941 | utilization |

*Use qualifiers with descriptors like: "Primary Health Care/utilization"*

That last detail — the seven allowed qualifiers, with /utilization and /statistics & numerical data highlighted — is exactly what a precise PubMed search needs. The model now has enough to draft ("Primary Health Care/utilization"[MeSH] OR "Primary Health Care/statistics & numerical data"[MeSH]) AND "Hospitalization/prevention and control"[MeSH] and explain why each leg matters.

The use case generalizes: any research informatics workflow that needs controlled vocabulary mapping (PubMed, Cochrane, OVID) benefits from mesh_search + mesh_qualifiers + mesh_tree. For systematic reviews specifically, the qualifier list is the part that's hardest to remember and easiest to get wrong.

What's new in 1.4.0 (data-integrity release)

Three additions that change the depth of what the server can answer:

map_icd10_to_icd11 now returns an authoritative WHO mapping, not a text-search heuristic. The 2025-01 release of the WHO transition tables is bundled (5.4 MB raw / 0.95 MB gzipped) covering 11,243 ICD-10 categories. 1,461 of those have multiple WHO-documented ICD-11 candidates — the tool surfaces the primary mapping plus all alternatives, with Foundation/Linearization URIs ready to navigate into ICD-11.
validate_codes is a new batch validator. Pass up to 50 { code, terminology } pairs and get back per-item { valid, active, title, replaced_by, source, error }. Designed for retrospective database analysis: flag codes that no longer exist, surface ICD-10 → ICD-11 replacements at scale, grade activity status where the source terminology exposes it (SNOMED's active flag, LOINC's STATUS field).
terminology_versions + terminology_diff for pipeline maintainers. The first lists current version, release date, publisher, and update cadence across all 8 terminologies. The second is guidance-only for terminologies without bundled history — except for ICD-10, where the bundled transition tables let it surface a real cross-revision summary (1:1 mappings vs splits vs average alternatives when split).

Together with the per-tool language parameter added to SNOMED + MeSH, that's four sub-tasks shipped as one data-integrity release. The earlier 1.3.0 added MCP Prompts (orchestration templates) and Resources (in-process reference content) — both visible in clients like LobeChat and Claude Desktop as one-click actions.

What the server doesn't claim to do

A few things worth being explicit about, because the README is honest about them and the LLM should be too:

map_loinc_to_snomed returns guidance, not a mapping. Direct LOINC ↔ SNOMED CT mappings live in UMLS Metathesaurus (license required) or the LOINC SNOMED CT Expression Association files (LOINC license required).
map_snomed_to_icd10 also returns guidance only today. The authoritative source is SNOMED International's ICD-10 Complex Map refset (447562003), which needs a Snowstorm instance with the refset loaded — planned as Phase 13.7 once that's tractable.
SNOMED tools are off by default because the historical public IHTSDO Snowstorm endpoint was retired (HTTP 410 Gone). Operators with an IHTSDO license and a self-hosted Snowstorm instance flip them on with ENABLE_SNOMED_TOOLS=true SNOMED_BASE_URL=....
None of this is a substitute for clinical judgment. It's a lookup layer for already-known codes, not a diagnostic tool.

Under the hood, briefly

For developers curious about the engineering: TypeScript on Node 20+, bundled with esbuild, built around a token-bucket rate limiter (5 req/s for WHO, 10 req/s for NLM, 20 req/s for RxNorm) and exponential-backoff retry with ±25% jitter. WHO OAuth tokens are cached using the actual expires_in from the API response, not a hardcoded TTL. Every default tool declares outputSchema and returns structuredContent alongside markdown — so MCP clients that consume structured data get typed objects, not parsed prose. The 313-test Vitest suite (unit + contract via nock + integration against live APIs gated by env flag) gates CI on PR. A daily integration cron catches upstream API drift — work that already caught three silent production regressions where the API had drifted and the client gracefully returned empty data.

Two transports: stdio (default — Claude Desktop, IDE clients) and Streamable HTTP. The HTTP path runs on Cloudflare Workers at the edge by default — single web-standard fetch handler, ~0.95 MB gzipped including the bundled CID-10 (DataSUS V2008) and ICD-10 → ICD-11 (WHO 2025-01) datasets, well within Cloudflare's 3 MB compressed script limit. Same source tree; per-isolate cache + rate limiter (KV + Durable Object swap available when traffic crosses the threshold).

It's MIT licensed. The medical terminology content has its own licenses, all linked in the README and surfaced as the info://licenses Resource.

Try it

npm: https://www.npmjs.com/package/medical-terminologies-mcp
GitHub: https://github.com/SidneyBissoli/medical-terminologies-mcp
Hosted endpoint: https://medical-terminologies-mcp.sidneybissoli.workers.dev/mcp (Streamable HTTP, Cloudflare Workers)
Smithery: https://smithery.ai/server/@SidneyBissoli/medical-terminologies-mcp
Glama: https://glama.ai/mcp/servers/SidneyBissoli/medical-terminologies-mcp
mcpservers.org: https://mcpservers.org/servers/sidneybissoli/medical-terminologies-mcp
MCP Registry: io.github.SidneyBissoli/medical-terminologies-mcp

WHO API credentials (free): https://icd.who.int/icdapi.

Issues, PRs, and use-case reports welcome — especially from clinical informatics teams, research informatics groups, and public-health data analysts using LLMs in real workflows. There's a real gap between "LLM as scribe" and "LLM with reliable terminology access," and closing it is what this server is for.

DEV Community: Sidney da S. P. Bissoli

Your MCP server changed. Its version didn't. Here's how to catch it.

Where this came from

1. Lock what the client sees, not what the code says

2. Make the version bump the only way out

3. Green tests prove the code; a post-deploy check proves what's served

4. The lock only protects you from now on, so replay the history

5. Two releases that don't even start

6. A minor release that removed six tools

7. The replay was wrong once, too

8. Check the probe before you write the lock

What I would do first, next time

Building an MCP server for financial data: lessons learned

1. Your source will lie to you with HTTP 200

2. "Last minus first" is wrong for half of the interesting series

3. Ordering is not a property of the endpoint

4. Two transports, one registry — or you will ship two products

5. The runtime will veto your validator

6. A field that can be null must say so, or a validating client rejects everything

7. Provenance is a contract, and the timestamp is the hard part

8. Latency is queue depth, not request count

9. Hand-curated catalogues rot; verify them against the source

10. Telemetry that counts by status code is blind to the errors you most need

11. Directory listings drift too

What I would do first, next time

How to query Brazilian economic data with AI using MCP (Selic, IPCA, exchange rates, Focus)

What you get

1. Connect it (pick one)

2. Ask questions

3. Read the provenance block

4. Why not let the model call the REST API itself?

Links

Seven medical terminologies, one MCP server: a practical walkthrough for clinical and research use

Setup in 60 seconds

Use case 1: sepsis triage — finding the right LOINC for procalcitonin

Use case 2: medication reconciliation — breaking down a combination product

Use case 3: evidence synthesis — building a precise PubMed search with MeSH

What's new in 1.4.0 (data-integrity release)

What the server doesn't claim to do

Under the hood, briefly

Try it

6. A field that can be `null` must say so, or a validating client rejects everything