Versioning Tools & Schemas
Evolve your server without breaking clients.
Versioning Tools & Schemas is a free MCP Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Clients Depend on Your Shapes
Once others connect, they rely on your tool names and argument shapes. Changing them carelessly breaks every client at once.
Additive Changes Are Safe
Adding an optional parameter with a default keeps old callers working. They simply ignore the new field they do not send.
def search(q: str, limit: int = 10) -> list:
...Breaking Changes Hurt
Renaming a tool, removing an argument, or making one required is breaking. Existing clients suddenly send calls that no longer fit.
Add, Then Deprecate
To evolve a field, add the new one and keep the old. Mark the old as deprecated in its description so callers know to migrate.
Version in the Tool Name
For a real break, ship a v2 tool beside v1. Both run for a while, letting clients move over at their own pace.
@mcp.tool(name="search_v2")
def search_v2(query: str) -> list:
...The Server Reports Its Version
Your server announces a name and version during the handshake. Bump it so clients can see which release they connected to.
mcp = FastMCP("my-server")
# version surfaces in server infoFollow Semantic Versioning
Use semver: bump patch for fixes, minor for additive features, and major when you make a breaking change. The number tells a story.
Widen, Don't Narrow, Outputs
Adding a field to a result is usually safe; removing one is breaking. Treat your output schema as a promise clients parse.
Keep a Changelog
Record every tool and schema change in a changelog. Users upgrading need to see what moved, what is new, and what is gone.
Give Deprecations a Sunset
Announce when an old tool will be removed. A clear sunset date pushes migration without yanking the rug from anyone abruptly.
Test Against Old Clients
Before release, run your tests as an older client would call you. That catches accidental breaks the type checker cannot see.
Quick Check
Which change to an existing tool is safe for current clients?
Recap: Evolving Safely
Prefer additive changes, deprecate before removing, ship v2 for real breaks, follow semver, and keep a changelog. You can ship with confidence! 🚀
Frequently asked questions
Is the “Versioning Tools & Schemas” lesson free?
Yes — the full text of “Versioning Tools & Schemas” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Versioning Tools & Schemas”?
Evolve your server without breaking clients. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Versioning Tools & Schemas” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Layered Server Architecture
- Config & Secrets via Environment
- Idempotent, Side-Effect-Aware Tools
- Versioning Tools & Schemas