Skip to main content
A badge tells a visitor how well your MCP server is built before they read a line of your README. It shows the latest score from mcpscore.dev and links to the full report.
That snippet renders as this badge, live from mcpscore.dev: mcpscore Replace the DeepWiki address with your server’s, URL-encoded, in both places. The report page on mcpscore.dev gives you the snippet with that already done.

​
Step 1: Audit your server on mcpscore.dev

Open mcpscore.dev, paste your server’s URL, and run the audit. When it finishes you are on your server’s report page. The badge reads its score from that audit. A server that has never been audited on mcpscore.dev shows no data.

​
Step 2: Copy the snippet into your README

The report page has a Markdown snippet and an HTML snippet. Paste one into your README:
Check it: the badge shows your score as a percentage, the same number as the report page. DeepWiki’s 96/114 shows as 84. The url parameter must match the audited URL exactly. Add a trailing slash to the DeepWiki address and the same server shows no data:
This is why copying the snippet from the report page is safer than typing it.

​
Step 3: Re-audit to update the badge

Every audit of the same URL on mcpscore.dev updates the badge. Your README never changes, because the badge URL names the server, not one audit. The link always opens the server’s latest report. The badge image is cached for 5 minutes, so a new score appears within that time. Runs of the CLI and the GitHub Action stay on your machine or your CI runner and do not update the badge. Re-audit on mcpscore.dev after a release to refresh it.

​
Read the badge

The number is the main score as a percentage. Its color follows the score ramp: The ring before the word mcpscore has four quarters, one per category, clockwise from the top right: Protocol, Primitives, Security & Auth, Readiness. Each quarter takes the color of that category’s result.
  • The badge is GET /api/v1/servers/badge.svg?url=<server URL>. It returns the most recent completed audit for that exact URL, with Cache-Control: public, max-age=300.
  • Requesting the badge never starts an audit. It is a read-only lookup, so a README with heavy traffic sends no requests to your server.
  • The link target /s?url= serves a page with your score in its preview tags, so a shared link unfurls with the real score, then redirects to the report.
  • mcpscore.dev audits anonymously. A server behind auth gets a partial audit there. To score it fully, run the CLI with a credential, as in Audit a server behind auth.

​
When it looks wrong

The badge says no data but you audited the server
  • Cause: the url parameter differs from the audited URL, often by a trailing slash or a path segment.
  • Fix: copy the snippet from the report page, which encodes the exact address you audited.
The badge shows an old score
  • Cause: the 5-minute cache, or the new audit ran against a different URL.
  • Fix: wait five minutes, then compare the url in the snippet with the URL of the new audit.
The badge did not change after a CI run
  • Cause: CLI and Action runs do not report to mcpscore.dev.
  • Fix: re-audit the server on mcpscore.dev.
The badge says partial
  • Cause: the server requires auth, and mcpscore.dev audits without credentials.
  • Fix: nothing is broken. The number covers the auth, TLS, and transport surface only.

​
Recap

  • Audit your server on mcpscore.dev.
  • Copy the snippet from the report page into your README.
  • Re-audit on mcpscore.dev to update the badge.

​
What’s next

Improve your score

The rules servers fail most, and how to fix them

Scoring methodology

What the number on the badge measures