mcp spec check — Ensure your MCP server is ready for the…

Pitch

Description

Comments

About this project

mcp-spec-check is a tool designed to assess the readiness of remote MCP servers for the upcoming 2026-07-28 MCP spec release. With a quick check of your server, it provides insights into adoption of the new stateless core and highlights areas needing migration, ensuring you stay ahead of impending changes to the protocol.

Overview

mcp-spec-check is a vital tool designed to assess the readiness of your remote MCP server for the 2026-07-28 MCP specification release. It allows users to quickly evaluate server compatibility in just 30 seconds, ensuring minimal disruption during the transition to the new stateless core protocol.

npx mcp-spec-check https://your-server.com/mcp

The release on July 28 is not an immediate switch but rather the publication of the updated specification. Version negotiation will continue to operate while deprecated features will exist for a minimum of 12 months. This tool focuses on measuring the adoption of the new specifications rather than creating an urgency before an outage occurs.

Key Features

The upcoming MCP 2026-07-28 release represents the most substantial revision since the protocol's inception. The major changes include:

Removal of the initialize handshake and Mcp-Session-Id in favor of a stateless core.
Implementation of Mcp-Method / Mcp-Name routing headers as mandatory.
Transition from SSE elicitation to Multi Round-Trip Requests.
Modifications of several error codes.

As SDKs and clients begin adopting the stateless core, servers failing to migrate risk being left behind as support phases out. mcp-spec-check performs black-box probing on your live endpoint without requiring code access, delivering direct insights into server status along with links to migration documentation.

Ecosystem Readiness

An extensive scan conducted on July 12, 2026, against 7,850 servers in the official MCP registry revealed that out of 4,356 accessible servers, only one met all requirements. Notably, 90.8% were not yet prepared for the new specifications. A complete report detailing these findings can be accessed in the docs/scan-2026-07.md.

What mcp-spec-check Assesses

The tool provides a succinct report with a verdict stating ready for 2026-07-28: YES / NO / UNKNOWN based on the performance of three crucial checks:

discover
routing-headers
session-independence

Passing all three yields a YES, while any failure results in a NO. Additional checks provide warnings but do not impact the readiness assessment. Each assessment is followed by a letter grade as supplementary feedback.

Check	Description
`discover`	Replace the initialize handshake; servers must implement it
`routing-headers`	`Mcp-Method` / `Mcp-Name` required on every request for routing
`session-independence`	Protocol-level sessions are removed; server cannot pin sessions behind load balancers
`error-codes`	(warn) renumbers resource-not-found from `-32002` to `-32602`
`cache-metadata`	(warn) new caching metadata `ttlMs` / `cacheScope`
`mrtr`	(warn) replacement of SSE elicitation with `resultType` field
`deprecated-features`	(warn) usage of deprecated Logging features
`auth-metadata`	(warn) metadata discoverable at `/.well-known/oauth-protected-resource`

Validation of Verdicts

Each probe's accuracy is ensured through consistent validation against known truth servers:

Two reference servers are utilized in continuous integration (CI) environments.
A known-truth panel cross-checks behavior against established public servers, including GitHub’s MCP server.
The official conformance suite acts as an independent source of truth.

In case the tool provides an incorrect verdict, reporting this as a priority bug is encouraged, along with the relevant --json output.

Usage Examples

For human-readable reports:

npx mcp-spec-check <url>

For machine-readable outputs suitable for scripting:

npx mcp-spec-check <url> --json

For verbose outputs explaining the reasons for each check:

npx mcp-spec-check <url> --verbose

Incorporating authentication for secured servers:

npx mcp-spec-check <url> --bearer <token>

Exit codes are CI-friendly, allowing for seamless integration into automated workflows: 0 indicates readiness, 1 signals at least one failing check, and 2 indicates the inability to test.

How It Operates

mcp-spec-check employs pure black-box HTTP probes against live endpoints, requiring no code access or installations. It operates ethically, only probing servers voluntarily registered in the official MCP registry. Results from each probe are retained on the local machine, ensuring privacy while only aggregate data is published.

Comparison with Other Tools

Unlike the official conformance suite or YawLabs/mcp-compliance, which focuses on complex compliance tests, mcp-spec-check is uniquely positioned to deliver a quick, black-box evaluation specifically targeting the next MCP release.