MCP tool-schema reference & contract exercises for agent platforms (Cursor, Claude Desktop, custom runtimes).

If you already gate OpenAPI breaking changes with tools like OASDiff or policy checks in the spirit of SpecShield, this repo applies the same mindset to tools/list and tool I/O schemas — where HTTP can stay 200 while agent contracts still break.

What this is

A small commerce-catalog MCP server (Go, tinymcp) you can run locally, in CI, or on a free host. It exposes get_product and list_skus with versioned output controlled by CATALOG_SCHEMA_VERSION.

Use it to:

• Prototype agent flows against a stable catalog contract
• Reproduce silent drift (healthy HTTP, changed tool schemas)
• Optional: assert every URL in mcp.json is covered by an external watch (see CI)

Live endpoint

https://toolschema-kit.onrender.com/mcp

(Also: GET /health for liveness.)

Quick start

git clone https://github.com/kioie/toolschema-kit.git
cd toolschema-kit
CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp
# MCP: http://127.0.0.1:8080/mcp

Bump schema (diff exercise)

CATALOG_SCHEMA_VERSION=2026.06.02 CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp

Compare tools/list or tool outputs before/after — same idea as an OpenAPI diff, for MCP.

Cursor / Claude Desktop

mcp.json.example — point url at localhost or the live host above.

Production monitoring

Teams usually run a scheduled contract watch on MCP URLs (diff tools/list, alert on breaking changes). This repo stays vendor-neutral; one workflow shows DriftGuard coverage assert as an optional gate — swap in your own checker if you prefer.

Docs

Deploy

Keywords

MCP schema drift, tool-schema diff, OpenAPI-style breaking changes for agents, Cursor MCP contract test, tools/list monitoring, silent API drift, SpecShield alternative MCP, OASDiff for MCP.

License

MIT — see LICENSE.