If you maintain a public MCP server — on GitHub, in an MCP registry listing, or just shared internally — a health badge in your README is one of the cheapest trust signals you can add. It takes a couple of minutes and it answers the first question any developer has before wiring your server into their agent: does this thing actually work right now?
What a health badge should actually check
Before picking a badge provider, it's worth being clear on what the badge represents. A badge that just checks "is port 443 open" or "did the process return any HTTP response" isn't telling anyone much — an MCP server can be fully reachable and still be broken for real clients.
A badge worth putting in a README should reflect:
- Whether the
initializehandshake completes successfully - Whether
tools/listreturns without error - Whether the returned tool schemas match what was previously observed (i.e., no undetected drift)
If your badge only checks the first of those, it can go green while your tool contracts quietly change underneath your users.
The basic markdown pattern
Most badges are just an image linking back to a status page. The pattern in a README looks like this:
[](https://your-status-page-url)If you're using a badge service that generates a dynamic SVG (rather than a static shields.io badge you have to manually update), the URL points at an endpoint that re-renders on every request based on the latest check result. That's the important distinction: a badge is only useful if it's live, not a snapshot from whenever you happened to add it.
Option 1: Build it yourself
A rough version of this is straightforward to assemble:
- A scheduled job (cron, GitHub Actions on a schedule, etc.) that connects to your server, runs
initialize, thentools/list - A small store (even a JSON file or a key-value store) recording the last known-good schema and the timestamp of the last successful check
- A diff step comparing the new
tools/listresponse against the stored schema - An endpoint that renders an SVG badge — green/red/yellow — based on the latest result, which you link to from your README
This is entirely doable, but it's also the kind of infrastructure that's easy to let rot. The job silently stops running, or nobody updates the diff logic when you add a new tool, and six months later the badge is green out of habit rather than because anything is actually being checked.
Option 2: Use a service built for MCP
If you'd rather not maintain that plumbing, a service purpose-built for MCP monitoring handles the handshake, the schema diffing, and badge rendering for you. MCP Vitals, for example, runs the real initialize → tools/list handshake against your server on a schedule, flags schema drift automatically, and gives you a badge snippet to drop straight into your README — so the green checkmark actually means something and stays current without extra maintenance on your end.
Placement and framing
A few practical notes on where and how to add it:
- Put it near the top of the README, next to build status or license badges — it's part of the same "can I trust this" cluster of signals
- Link the badge to a status page or incident log, not just a bare pass/fail, so people can check history if the badge is ever red
- If your server has multiple tools with different stability, consider noting that in the linked status page rather than trying to cram it into the badge itself
Keep it honest
The worst outcome is a badge that's technically still there but no longer connected to anything real — a static image that says "healthy" because someone hardcoded it during setup. If you can't commit to keeping the underlying check running, it's better to have no badge than a stale one; a badge that turns out to be fake trust is worse for your reputation than not having one at all.
Done right, though, it's a small addition that gives every visitor to your repo an honest, at-a-glance answer — and saves you from fielding "is your server down?" messages that a badge could have answered on its own.