{"slug": "mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes", "title": "MCP-spec-audit, scan your MCP server for the July 28 spec changes", "summary": "Temrel released mcp-spec-audit, a static analysis tool that scans MCP server codebases for breaking, deprecated, and advisory changes ahead of the MCP 2026-07-28 spec revision, which reshapes the protocol around a stateless core by removing the initialize handshake and Mcp-Session-Id header. The tool classifies findings as BREAKS, DEPRECATED, or ADVISORY, generates a markdown migration checklist with file:line references, and exits with code 1 if any BREAKS findings are detected for CI integration.", "body_md": "Audit an MCP server codebase before the MCP 2026-07-28 spec revision lands. `mcp-spec-audit <path>`\n\nstatically scans the code, classifies every finding as **BREAKS**, **DEPRECATED**, or **ADVISORY**, and writes a markdown migration checklist with file:line references, each finding linking to the relevant spec material.\n\nIt pairs with the [mcp-spec-audit skill](/Temrel/temrel-agentic-toolkit/blob/main/skills/model-invoked/mcp-spec-audit): the skill lets an agent run the audit for you and summarize the findings; the CLI is the scanner itself, usable standalone or in CI.\n\n**Guarantees:** pure static analysis. No network calls, no code execution, and it never modifies the scanned codebase.\n\nThe [2026-07-28 release candidate](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) reshapes MCP around a stateless core. The `initialize`\n\nhandshake and the `Mcp-Session-Id`\n\nheader are gone, so any request can land on any server instance and sticky routing or shared session stores are no longer needed. The experimental 2025-11-25 Tasks API graduates with a changed lifecycle (`tasks/get`\n\n, `tasks/update`\n\n, `tasks/cancel`\n\n; `tasks/list`\n\nis removed). Roots, Sampling, and protocol-level Logging are deprecated with a 12-month window. Authorization is hardened around OAuth 2.1, and `tools/list`\n\nresponses gain `ttlMs`\n\nand `cacheScope`\n\nso clients can cache. Servers written against earlier revisions or SDK v1 will keep working for a while, but the migration is real work, and it is cheaper to find the sites now than after the window closes.\n\n| Severity | Meaning | Rules cover |\n|---|---|---|\n| BREAKS | Will not work against 2026-07-28; exit code 1 | Experimental 2025-11-25 Tasks API usage: `tasks/result` , `tasks/list` , `notifications/tasks/status` , `CreateTaskResult` , `taskSupport` , `io.modelcontextprotocol/related-task` and `model-immediate-response` _meta keys |\n| DEPRECATED | 12-month window; plan the replacement | Roots (`roots/list` , `list_roots` , `listRoots` ), Sampling (`sampling/createMessage` , `create_message` , `createMessage` ), protocol-level Logging (`logging/setLevel` , `notifications/message` , `send_log_message` , `sendLoggingMessage` ) |\n| ADVISORY | Review; the stateless revision replaces or obsoletes these | `Mcp-Session-Id` handling, `sessionIdGenerator` , initialize-handshake hooks, sticky sessions and session stores, API-key auth where OAuth 2.1 is now mandated, `mcp.server.fastmcp` imports (renamed `MCPServer` in Python SDK v2), CommonJS `require()` of the TypeScript SDK (v2 is ESM-only), monolithic `@modelcontextprotocol/sdk` imports and dependencies (v2 splits into `@modelcontextprotocol/server` and `@modelcontextprotocol/client` ), uncached `tools/list` calls that could honor `ttlMs` |\n\nPython and TypeScript/JavaScript get language-specific rules. Go and C# files are scanned too, but only by the language-agnostic protocol-string rules (JSON-RPC method names, headers, _meta keys).\n\n```\ncd tools/mcp-spec-audit\nnpm install\nnpm run build\nnpm link        # optional: puts `mcp-spec-audit` on your PATH\n```\n\nRequires Node 20+. During development, `npm run dev -- <path>`\n\nruns from source via tsx.\n\n```\nmcp-spec-audit <path> [--json] [--report <file>] [--no-report] [--rules <file>]\n```\n\n`<path>`\n\nis the root of the MCP server codebase (or a single file).`--json`\n\nswitches the terminal output to machine-readable JSON.`--report`\n\nsets the markdown report path (default`mcp-spec-audit-report.md`\n\nin the current directory);`--no-report`\n\nskips it.`--rules`\n\npoints at an alternative rules file.\n\n**Exit codes:** 1 if any BREAKS findings (CI-friendly), 0 otherwise, 2 on error.\n\nThe markdown report groups findings by severity, leads with a checkbox migration checklist (one item per triggered rule, with site counts), and lists every site as `file:line`\n\nwith the matched excerpt.\n\nRules are declarative data in [ rules.json](/Temrel/temrel-agentic-toolkit/blob/main/tools/mcp-spec-audit/rules.json); a new spec revision should be a rule-file change, not a code change. One rule looks like:\n\n```\n{\n  \"id\": \"my-new-rule\",\n  \"languages\": [\"python\"],\n  \"pattern\": \"\\\\bsome_removed_api\\\\b\",\n  \"flags\": \"i\",\n  \"severity\": \"deprecated\",\n  \"message\": \"What was found and why it matters.\",\n  \"replacement\": \"What to do instead.\",\n  \"specLink\": \"https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/\"\n}\n```\n\n`languages`\n\nis any of`python`\n\n,`typescript`\n\n(also covers JS),`go`\n\n,`csharp`\n\n, or`any`\n\n.`pattern`\n\nis a JavaScript regex matched per line;`flags`\n\nis optional.- Optional\n`fileName`\n\nrestricts the rule to an exact basename (used for`package.json`\n\ndependency checks). `severity`\n\nis`breaks`\n\n,`deprecated`\n\n, or`advisory`\n\n; only`breaks`\n\naffects the exit code.\n\nThe rules test suite validates every rule (unique id, compiling pattern, valid severity, spec link), so `npm test`\n\nafter editing is enough to catch mistakes. Verify any new API name against the official spec or SDK docs before encoding it; do not encode guesses.\n\nFalse positives are traded away aggressively; expect this tool to miss exotic cases rather than flag compliant code. In particular:\n\n- Matching is line-based regex, not full parsing. Identifiers split across lines, aliased imports, or dynamically built method strings are missed.\n- Whole-line comments are skipped, but trailing comments on code lines are still matched.\n- Generic names carry residual ambiguity:\n`createMessage`\n\n/`create_message`\n\nmay be another library's API, and`session_store`\n\n/sticky-session hits may belong to your web framework rather than MCP. These are worded conditionally and never severity`breaks`\n\n. - Absence cannot be detected: a server with no auth at all produces no auth finding. The\n`x-api-key`\n\nrule only catches visible legacy auth. `tasks/get`\n\nand`tasks/cancel`\n\nexist in both the experimental and graduated Tasks APIs, so they are not flagged on their own; the removed methods around them are.- Go and C# coverage is protocol-string level only.\n\n```\nnpm test\n```\n\nFixtures under `test/fixtures/`\n\ninclude a deliberately non-compliant Python server, a deliberately non-compliant TypeScript server (plus a CommonJS client and a legacy `package.json`\n\n), and a compliant pair asserted to produce zero findings. Tests pin the exact rule set each fixture must trigger and assert the rendered report contains no em dashes.\n\n[Subscribe to Temrel](https://spark.temrel.com/subscribe?utm_source=github&utm_medium=repo&utm_campaign=toolkit) for a new item every week.", "url": "https://wpnews.pro/news/mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes", "canonical_source": "https://github.com/Temrel/temrel-agentic-toolkit/tree/main/tools/mcp-spec-audit", "published_at": "2026-07-23 10:24:38+00:00", "updated_at": "2026-07-23 10:52:28.039447+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["Temrel", "MCP", "mcp-spec-audit", "Python SDK v2", "TypeScript SDK v2", "OAuth 2.1"], "alternates": {"html": "https://wpnews.pro/news/mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes", "markdown": "https://wpnews.pro/news/mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes.md", "text": "https://wpnews.pro/news/mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes.txt", "jsonld": "https://wpnews.pro/news/mcp-spec-audit-scan-your-mcp-server-for-the-july-28-spec-changes.jsonld"}}