Versioning
The MCP tool surface is independently versioned from the protocol version. Breaking changes are gated on a deliberate deprecation cycle; additive changes are continuous.
Three version dimensions
| Dimension | Current | What it covers |
|---|---|---|
| MCP protocol version | 2025-03-26 | JSON-RPC framing, transport, lifecycle. Negotiated via the MCP-Protocol-Version header at initialize. |
| Tool surface version | v0.1.0 | The set of tools, their input/output schemas, and the error codes they can return. Tracked internally as mcp_tool_surface_version. |
| Server build version | 0.1.0 (advertised in serverInfo) | The shipped code version. Surface version may stay stable across multiple build versions. |
What counts as breaking
The following are breaking and require a tool-surface version bump:
- Removing a tool from the surface.
- Renaming a tool.
- Removing or renaming a required input field.
- Tightening the type of an existing input or output field.
- Changing the meaning of an existing error code.
- Changing the semantics of an action result (the discriminated union shape).
The following are additive and ship without a version bump:
- Adding a new tool.
- Adding a new optional input field.
- Adding a new field to an output object.
- Adding a new error code (existing code paths unaffected).
- Improving descriptions, examples, or non-normative documentation.
Deprecation policy
Today no tool is deprecated; the deprecation policy ships ahead of need.
Detecting surface drift in your client
Call tools/list at startup and compare against the set your client knows about. New tools should be ignored gracefully; missing tools (compared to your client's expectation) should fail loud:
const { tools } = await client.listTools();
const names = new Set(tools.map((t) => t.name));
const required = ['memory.recall', 'rules.list', 'trust.check'];
const missing = required.filter((n) => !names.has(n));
if (missing.length > 0) {
throw new Error('Required tools missing from surface: ' + missing.join(', '));
}Why the protocol and surface versions are separate
The MCP protocol (2025-03-26) governs framing — how a request is routed, how a session is identified, what an initialize response looks like. The tool surface (v0.1.0) governs which application primitives you can call. They move on different cadences: protocol versions land roughly every 6 months; tool surface versions bump when Cortex's own product surface changes.
A client written today against v0.1.0 and 2025-03-26 keeps working as long as both versions stay live; the server will negotiate the protocol at initialize and reject mismatches there.