{"slug": "mcp-tool-pinning-a-compatibility-guide", "title": "MCP Tool Pinning: A Compatibility Guide", "summary": "A developer at an unnamed company proposes using a compatibility-aware tool, compat_gate.py, instead of simple SHA-256 pinning to manage MCP tool schema changes, because byte-level pins cannot distinguish between backward-compatible updates and breaking changes. The pinning approach triggers on every schema revision, including harmless description tweaks, while compat_gate.py diffs the inputSchema and replays recorded agent calls to stay silent on compatible updates and fail-closed on breaking ones.", "body_md": "# MCP Tool Pinning: A Compatibility Guide\n\n[MCP](/en/tags/mcp/)tool manifest to prevent \"rug-pulls,\" you're essentially telling your system to panic the moment a single bit changes. The problem we hit at work is that a server adding an optional parameter trips the alarm just as loudly as a server deleting a required one. The pin knows the contract changed, but it has no clue if that change actually broke the AI workflow.\n\nIn a production environment, an MCP tool schema breaking change narrows the set of valid calls, meaning a prompt that worked yesterday suddenly fails today. Conversely, a backward-compatible change just expands the options. A simple byte pin can't tell the difference. To solve this, I've been using `compat_gate.py`\n\nto diff the `inputSchema`\n\nand replay recorded agent calls—it stays silent on compatible updates and fails-closed on breaking ones.\n\n## Why manifest pinning triggers on every update\n\nThe pin operates on a canonical SHA-256 of the `name + description + inputSchema`\n\n. While it's smart enough to ignore JSON whitespace or key ordering, it's paranoid about meaning.\n\nThe reality of the MCP spec is that revisions happen constantly. Servers update, descriptions are tweaked to help the LLM understand the tool better, and versions shift. Every single one of these events flips the pin's bit. We've realized that tracking change isn't the same as controlling compatibility. A changed contract isn't necessarily a broken one.\n\n## Defining \"Breaking\" in Tool Schemas\n\nThis comes down to basic subtyping. A schema defines a set of valid argument objects.\n\n**Backward-compatible:** The new set contains the old one. Every call that validated before still validates now.**Breaking:** The new set is smaller. Some previously valid calls now fail.\n\nIf you're building a real-world LLM agent deployment, you can't rely on a hash alone. You need a compatibility check that understands the schema logic, not just the bytes. This allows the team to accept harmless updates (like better descriptions) without manually resetting pins every time a vendor pushes a minor patch.\n\n[Next Automated PR Reviews: My Experience with Coding Agents →](/en/threads/2690/)", "url": "https://wpnews.pro/news/mcp-tool-pinning-a-compatibility-guide", "canonical_source": "https://promptcube3.com/en/threads/2705/", "published_at": "2026-07-24 03:47:00+00:00", "updated_at": "2026-07-24 12:11:27.743845+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["MCP"], "alternates": {"html": "https://wpnews.pro/news/mcp-tool-pinning-a-compatibility-guide", "markdown": "https://wpnews.pro/news/mcp-tool-pinning-a-compatibility-guide.md", "text": "https://wpnews.pro/news/mcp-tool-pinning-a-compatibility-guide.txt", "jsonld": "https://wpnews.pro/news/mcp-tool-pinning-a-compatibility-guide.jsonld"}}