Pre-release checks for MCP servers

MCP Doctor

Find problems before you release your MCP server.

An MCP server can connect and still fail when an agent tries to use it. MCP Doctor checks for those hidden problems and tells you what to fix first.

Run MCP Doctor See an example report

The hidden problem

A server can connect and still be broken.

A successful connection only proves that the server answered once. Its tools can still have invalid schemas, unclear instructions, broken responses, timeouts, or cleanup problems. MCP Doctor checks those parts before release.

GitHub Actions

Check every MCP change before you merge.

Run a passive check on each pull request. MCP Doctor shows what passed, what failed, and what to fix first.

Set up GitHub Actions

Measured performance

MCP Doctor checked this server in 333 ms.

Across 8 successful runs, MCP Doctor checked the server in 287–838 ms and wrote four CI reports.

Typical check
333 ms
Install time
330× faster
Observed range
287–838 ms

Eight measured MCP Doctor checks

The diagnosis step took 287–838 milliseconds across eight successful GitHub Actions runs; the rounded median was 333 milliseconds.

This measures only MCP Doctor’s diagnosis step in a repository-owned TypeScript harness on GitHub-hosted Ubuntu 24.04 runners. It excludes checkout, builds, CLI acquisition, capability checks, report verification and upload, queueing, and comments. It is not total workflow time or a guarantee for every repository.

Eight measured MCP Doctor checks
RunDuration (milliseconds)
MCP Doctor check · run 1838
MCP Doctor check · run 2331
MCP Doctor check · run 3334
MCP Doctor check · run 4422
MCP Doctor check · run 5299
MCP Doctor check · run 6287
MCP Doctor check · run 7317
MCP Doctor check · run 8449

mcp-harness GitHub Actions Eight successful diagnosis steps were measured from their GitHub Actions log-group start to the next step on August 27, 2026.

Check time: 287–838 ms

Same GitHub Actions harness · 5 Cargo installs vs. 8 prebuilt-binary downloads

The Agent Skill

Let your coding agent run the same MCP check.

The Agent Skill helps compatible coding agents run a passive mcp-doctor check, read its redacted report, and start with the first fix.

Set up the Agent Skill Open in Smithery

Install the CLI first · Optional · Passive checks only

  • OpenAI

    ChatGPT · Codex

  • Anthropic

    Claude Code

  • Cursor

    Cursor Agent

  • Microsoft

    VS Code

  • GitHub

    GitHub Copilot

  • Kiro

    Kiro IDE · Kiro CLI

Why this matters now

Downloads of the official MCP SDK are rising fast.

The distribution signal grew by more than 100×

Monthly npm downloads reported for the official @modelcontextprotocol/sdk package rose from 1.87 million in March 2025 to 191.92 million in July 2026.

Downloads include CI, caches, automated installs, repeat installs, and five API-reported zero days with no published explanation. They are not unique developers, active users, deployed servers, customers, successful tasks, revenue, or proof that a product needs MCP.

The distribution signal grew by more than 100×
MonthDownloads
March 20251,874,545
April 20254,212,709
May 202520,933,359
June 202516,837,593
July 202521,605,761
August 202524,658,353
September 202531,258,519
October 202531,805,028
November 202535,008,987
December 202538,516,712
January 202650,249,918
February 202671,656,771
March 2026141,911,796
April 2026140,092,905
May 2026153,164,130
June 2026165,176,305
July 2026191,923,439

npm download-count API The 518 public daily counts were grouped into 17 complete calendar months and reviewed August 24, 2026.

Official TypeScript MCP SDK downloads

How it helps

How it helps

  1. 01

    Inspect passively

    Validate discovery, definitions, schemas, protocol behavior, and runtime boundaries without calling a tool.

  2. 02

    Exercise reviewed behavior

    Replay explicit scenarios or generate bounded cases only after granting exact authority to the selected tool.

  3. 03

    Keep evidence

    Use the same redacted result in human, JSON, JUnit, Markdown, and badge output for local fixes and CI.

A better CI signal

When a check fails, it should tell you what to fix.

A CI result can be more specific than pass or fail

mcp-doctor v0.4.0 defines 52 stable finding codes: 1 informational, 5 warnings, 42 errors, and 4 critical findings.

These are diagnostic definitions across passive and active commands—not common findings, observed defects, server scans, incidence rates, a guarantee that every code runs in passive inspect, or proof of test coverage.

A CI result can be more specific than pass or fail
SeverityFinding codes
Informational1
Warning5
Error42
Critical4

mcp-doctor v0.4.0 finding model FindingCode variants and their code-owned severities were counted in the immutable v0.4.0 source and reviewed August 24, 2026.

mcp-doctor finding codes by severity

What MCP Doctor checks—and what a pass does not prove.

Straight answers about connections, active diagnostics, CI, and the limits of a passing result.

What is MCP, and why does implementation quality matter?

Model Context Protocol lets compatible AI applications connect to outside tools, data, and workflows. That connection becomes another product surface: its permissions, schemas, descriptions, results, and failure behavior need to be as intentional as the interface people use directly.

Why isn’t a successful connection enough?

A handshake proves only that the server answered once. It can still advertise unclear tools, invalid schemas, broken result contracts, protocol failures, timeouts, or unsafe cleanup. mcp-doctor checks the surface a client actually discovers.

What can mcp-doctor find?

It diagnoses protocol and JSON-RPC problems, weak agent guidance, invalid or unsafe schemas, result-contract mismatches, timeouts, crashes, output-limit failures, cleanup problems, and repeatability gaps—then identifies the first actionable issue without hiding independent findings.

Will mcp-doctor call my tools or change data?

Passive inspect does not call listed tools. It still starts the local command or contacts the remote endpoint you select. Active check, break, and reject diagnostics make real calls only with explicit authority and should use disposable data in a suitable test environment.

Where does mcp-doctor fit in development and CI?

Run passive inspection while a change is fresh, fix the first actionable failure, and repeat the same pinned check in CI. Stable exits and redacted JSON, JUnit, Markdown, and badge artifacts give developers, coding agents, and automation one bounded result to work from.

Does a passing result mean my MCP server is production-ready?

No. It is evidence from one scoped diagnostic run, not certification or proof of security, authorization, model success, or universal MCP conformance. mcp-doctor complements product tests, integration tests, security review, and human judgment; it does not replace them.

Before your next release

Check your server before users find the problems.

Run MCP Doctor locally or add the same passive check to each pull request.

Run MCP Doctor Set up GitHub Actions

Building a public MCP server? Tell us what you’re working on