Versioning and Maintenance: The 95% Server-Side Advantage
James opened his TutorClaw project from Chapter 58 and looked at the shim skill file. About fifty lines. A few tool declarations, a PRIMM-Lite fallback section, and a pointer to the MCP server. Then he looked at the MCP server code. Nine tools. A pedagogical engine. Assessment logic. Code execution sandbox. Content delivery. Rate limiting. Tier gating. Thousands of lines of intelligence, all running on the server.
"If I wanted to improve the assessment logic," he said, "I would change the server code, push the update, and every learner would get the improvement the next time they asked for an assessment. They would not need to do anything."
Emma nodded. "Correct."
"But if I added a tenth tool, the learner's shim would not know about it. Their agent would not discover the new tool unless the shim was updated."
"Also correct. And that distinction is the entire versioning strategy."
James leaned back. "At the warehouse, we used a parts catalog. When a machine got a motor upgrade, most of the replacement parts stayed the same: bolts, belts, filters. The catalog version did not change for those. But when the motor had new mounting brackets, the catalog needed an update because the parts list changed. The motor itself did not care about the catalog version. The catalog existed so that the person ordering parts would get the right list."
"That is exactly what is happening here," Emma said. "The MCP server is the motor. The shim skill is the parts catalog."
You are doing exactly what James is doing. You shipped a product in Chapter 58, published it to ClawHub in Chapter 58 Lesson 16, and now face the question every shipped product faces: what happens when you need to change it?
Where the Intelligence Lives
The answer starts with the architecture you already know. TutorClaw has three components:
| Component | What It Contains | Who Runs It |
|---|---|---|
| MCP Server | 9 tools, pedagogical engine, assessment, code execution, tier logic | Panaversity (VPS) |
| R2 Content Layer | Chapter content, exercises, rubrics | Cloudflare (edge network) |
| Shim Skill | Tool declarations, PRIMM-Lite fallback, server pointer | Learner (local OpenClaw) |
The intelligence lives on the MCP server and the R2 content layer. The shim skill is a thin connection layer: it tells the learner's OpenClaw agent where to find the server and what tools are available. The shim contains no pedagogical logic, no assessment rules, no content. It is a pointer and a fallback.
This separation was an architecture decision. You traced its origins in Lesson 4: the Platform Inversion put the learner's machine in charge of compute while keeping the intelligence server-side. The economic consequences played out in Chapter 59. Now you see the maintenance consequence: when the intelligence improves, only the server changes.
The 95% Case: Invisible Improvements
Consider the kinds of improvements you might make to TutorClaw after shipping:
| Improvement | What Changes | Shim Update? |
|---|---|---|
| Add three new chapters of content to R2 | R2 bucket | No |
| Improve the pedagogical engine's prompting | MCP server code | No |
| Fix a bug in the assessment scoring logic | MCP server code | No |
| Add better error messages for edge cases | MCP server code | No |
| Adjust tier limits for free users | MCP server configuration | No |
| Improve code execution sandbox security | MCP server code | No |
| Update exercise rubrics | R2 content | No |
| Optimize server response times | MCP server infrastructure | No |
Every one of these improvements happens on Panaversity's side. The learner's shim skill is unaffected. The learner does not need to run an update command. They do not need to know the improvement happened. The next time they use TutorClaw, the improvement is there.
This is the 95% case. The vast majority of product improvements in an MCP-first architecture are server-side changes that propagate to every user instantly. No update notifications. No version compatibility issues. No "please restart to apply changes." The server changes; the user benefits.
The reason this works is the architecture itself. The shim skill declares which tools exist and where the server is. As long as those declarations remain accurate, the shim does not care what happens inside the server. The pedagogical engine could be rewritten from scratch, and the learner's experience would simply improve without any action on their part.
The 5% Case: When the Shim Must Change
Not every change is invisible. Some changes alter the contract between the shim skill and the MCP server. When the contract changes, the shim must be updated so the learner's agent sees the new contract.
Three categories of change require a shim update:
Tool surface changes. If you add a new tool (a tenth tool for, say, peer-to-peer study groups), the shim's tool declarations must include it. If you remove a tool, the shim must stop declaring it. If you rename a tool's parameters, the shim must reflect the new names. The learner's agent discovers tools through the shim. If the shim declares nine tools but the server has ten, the agent will never call the tenth.
Transport changes. If you move the MCP server to a new URL, or switch from HTTPS to a different transport, the shim's server pointer must be updated. The learner's agent connects to whatever address the shim specifies. A stale address means a broken connection.
Breaking protocol changes. If the MCP specification itself introduces a breaking change (a new version of the protocol that changes how tools are declared or how results are returned), both the server and the shim must be updated to speak the new protocol version.
These three categories share a common trait: they change the interface, not the implementation. The server's internal logic can change freely. The contract between shim and server cannot change without updating both sides.
Semantic Versioning for the Shim
Semantic versioning (MAJOR.MINOR.PATCH) applies to the shim skill, not the server. The server changes continuously; the shim version bumps only when the shim changes.
| Version Segment | When It Bumps | Example |
|---|---|---|
| PATCH (0.1.1) | Bug fix in the shim itself (typo in fallback, config fix) | Fixed a formatting error in PRIMM-Lite offline mode |
| MINOR (0.2.0) | New tool added, optional feature added, non-breaking expansion | Added a peer study tool; existing tools still work |
| MAJOR (1.0.0) | Breaking change: tool removed, parameter renamed, transport moved | Removed a deprecated tool; old shims stop working |
The examples use 0.x versions because TutorClaw's shim is early in its lifecycle. Pre-1.0 signals that the interface may still evolve. The same MAJOR.MINOR.PATCH semantics apply once the shim reaches 1.0.0.
Notice the asymmetry. The server might receive dozens of improvements between shim version bumps. Content is added, bugs are fixed, performance is improved, and the shim version stays the same because none of those changes touch the shim. Then one day a new tool is added, the shim is updated to declare it, and a MINOR version bump is published.
The user does not need to track server changes. The shim version is the only version that matters to them. And the shim version changes rarely.
Communicating Changes
The 95% server-side advantage solves a maintenance problem, but it creates a communication problem. If the product improves without the user noticing, how do they know it is improving?
Three approaches work together:
Changelogs on ClawHub. Each shim version bump includes a changelog entry describing what changed. But you can also publish server-side changelogs that describe improvements users will experience without needing to update. "New chapter content available" or "Assessment feedback is now more detailed" communicates value without requiring action.
In-product signals. The MCP server itself can communicate improvements. When a new chapter is available, the get_chapter_content tool can mention it. When assessment logic improves, the response quality itself is the signal. The product communicates its improvements through its behavior.
Version check patterns. The shim skill can include a version field that the server compares against the current shim version. If the server detects that a learner's shim is outdated (missing a new tool, using a deprecated parameter name), it can return a gentle suggestion in its responses: "A newer version of the TutorClaw skill is available on ClawHub with additional capabilities."
These patterns keep users informed without interrupting their workflow. The goal is communication, not forced updates.
Try With AI
Exercise 1: Classify Your Changes
Think of a product you have built or used. List ten improvements you might make to it. Use this prompt to classify each as server-side or client-side:
I have a product built with an MCP-first architecture. The
product has a remote MCP server (intelligence) and a local
shim skill (tool declarations and server pointer).
Here are ten improvements I want to make:
1. [improvement]
2. [improvement]
...
10. [improvement]
For each improvement, classify it as:
- Server-side (no shim update needed): explain why
- Client-side (shim update required): explain what changes in the shim
Then calculate: what percentage of these improvements are
server-side? How does this compare to the 95% pattern?
What you are learning: The 95% number is not arbitrary. It emerges from the architecture itself: when intelligence is server-side and the client is a thin pointer, most improvements happen where the intelligence lives. Classifying your own improvements reveals whether your architecture has the same property, or whether your client is thicker than it needs to be.
Exercise 2: Design a Version Bump
Imagine you are adding a new tool to TutorClaw (a study group coordination tool). Use this prompt to plan the version release:
I am adding a new tool to my MCP-first application. The tool
is called "coordinate_study_group" and it helps learners form
study groups around specific chapters.
Plan the shim skill update:
1. What changes in the shim file? (tool declaration)
2. What version bump is appropriate? (MAJOR, MINOR, or PATCH)
3. What should the changelog entry say?
4. How should existing users be notified?
5. What happens to users who do not update their shim?
(They still have the old 9 tools; they just miss the new one)
Write a complete changelog entry for this version bump.
What you are learning: A version bump is a communication act, not just a number change. The changelog tells users what changed and why. The version segment (MAJOR, MINOR, PATCH) tells them how much changed. And the answer to "what happens if they do not update?" reveals the backward-compatibility characteristics of your architecture. In the MCP-first model, old shims still work; they just miss new capabilities.
Exercise 3: Write a Version Check Response
Design the server-side logic for detecting an outdated shim. Use this prompt to think through the UX:
My MCP server knows the current shim version is 0.3.0. A
learner connects with shim version 0.2.0 (missing one tool
declaration from the 0.3.0 update).
Design the version check behavior:
1. Should the server refuse to work with the old shim? Why or why not?
2. What message should the server include in its responses to
let the learner know an update is available?
3. How do you balance "informing the user" with "not annoying
the user"?
4. At what version gap (if any) should the server require an update?
Write the exact text of a gentle version notification that
would appear in a tool response.
What you are learning: Version compatibility is a UX question as much as a technical one. The MCP-first architecture is naturally backward-compatible (old shims work, they just miss new tools), which means forced updates are rarely necessary. The challenge is communicating that an update is available without disrupting the learner's workflow. This is the same challenge every app store, package manager, and auto-updater faces: how to be helpful without being intrusive.
James sat with the classification exercise for a moment. He had listed twelve improvements he might make to TutorClaw: better prompts for the pedagogical engine, more chapter content, a practice quiz mode, improved error messages, a new tool for code review, faster server responses, a mobile-friendly formatting option, better assessment rubrics, security patches, a study planner tool, revised exercise difficulty curves, and more detailed progress reports.
Ten of the twelve were server-side. Only two (the code review tool and the study planner tool) required shim updates because they added new tools to the surface.
"Ten out of twelve," he said. "And even the two that need a shim update, the old shim still works. The learner just does not see the new tools until they update."
Emma nodded. "That backward compatibility is not free. It comes from the architecture. The shim declares tools; the server implements them. As long as you do not remove or rename existing tools, old shims keep working."
"It is like the parts catalog," James said. "When we added new accessories to a machine at the warehouse, the old catalog was not wrong. It just did not list the new accessories. Anyone with the old catalog could still order every part they had before. They just did not know the new options existed until they got the updated catalog."
"That is the advantage of a thin client," Emma said. "The less the client knows, the less can go stale." She paused. "I should be honest about something. This versioning pattern works well for MCP servers on ClawHub. I would not assume it transfers directly to npm packages or PyPI libraries or mobile app stores. Each ecosystem has different conventions for how updates are discovered, how backward compatibility is handled, and what users expect. I know the MCP pattern well. I have not shipped packages in every ecosystem, and each one has its own culture around versioning."
James considered that. "So the strategy is specific to the architecture."
"The principle is general: thin clients version rarely. But the details, the notification patterns, the update cadence, the backward-compatibility guarantees, those depend on where you are publishing. Versioning keeps your existing users current. Distribution is how new users find you."