whetstone_DSL/docs/mcp_versioning_and_compatibility.md

MCP Versioning and Compatibility (Agent Guide)

Why this exists

Agents can fail for reasons that are already fixed in newer MCP runtime builds. This guide defines where to check runtime/tool versions and where fix records are tracked.

Runtime version header

Whetstone MCP now exposes a whetstoneVersionHeader in:

• initialize.result
• ping.result
• tools/list.result
• tools/call.result

Header fields:

• runtimeVersion: MCP runtime version (for example 0.8.4)
• protocolVersion: MCP protocol date string
• toolContractDefaultVersion: default contract version for tools
• toolSurfaceSchemaVersion: schema snapshot version
• toolCount: tool count in the running server
• toolSurfaceFingerprint: deterministic fingerprint of tool names
• compatibilityLedger.path: path to the issue/fix ledger JSON
• compatibilityLedger.version: ledger schema/snapshot version

Tool-level contract header

Each tools/list entry includes x-whetstone:

• contractVersion
• compatibilityLedger

Compatibility ledger

Machine-readable ledger:

• docs/mcp_compatibility_ledger.json

Use this for checks like:

• "Issue reproduced on runtimeVersion=0.8.1"
• "Ledger says fixed in 0.8.4"
• "Action: update server runtime before more debugging"

Recommended triage flow for agents

1. Call initialize (or ping) and capture whetstoneVersionHeader.
2. If behavior seems wrong, read docs/mcp_compatibility_ledger.json and match symptom tags.
3. If runtimeVersion < fixed_in, report upgrade recommendation first.
4. Only escalate to deep debugging after version mismatch is ruled out.

Notes

• Keep ledger entries small and concrete (symptom, affected tools, fixed version).
• Add entries when a recurring failure pattern is fixed deterministically.