MCP server versioning

Protocol version negotiation

The MCP initialize handshake is where protocol version negotiation happens. The client sends the highest protocol version it supports; the server responds with the version it will use for the session:

// Client sends:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",  // client's highest supported version
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "claude-desktop", "version": "1.0.0" }
  }
}

// Server responds:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",  // version the server will use
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "my-mcp-server", "version": "1.2.0" }
  }
}

The official MCP SDK handles this negotiation automatically — the SDK version you install supports the protocol versions defined at the time of release. When a new protocol spec version is published, the SDK is updated to support it. You do not need to write version negotiation code. However, you must be aware that upgrading the SDK may change the protocolVersion field in the initialize response — this can break clients that check for a specific protocol version string. Run your protocol compliance tests after every SDK upgrade to catch this.

The serverInfo.version field in the initialize response is your application version — change it with every deployment. This field appears in AliveMCP's probe history, giving you a deployment log from uptime monitoring: each time the version string changes in probe results, it marks a deployment. Use semantic versioning: 1.2.3 where patch bumps are non-breaking, minor bumps add new tools, and major bumps indicate breaking tool schema changes.

Breaking vs non-breaking tool schema changes

AI clients cache the tools/list response. A client that has cached your old tool schema will send tool calls using the old parameter names and types. Breaking changes break those calls:

Schema snapshot test to catch breaking changes

The schema snapshot test catches breaking changes before they reach production. It stores a SHA-256 hash of the sorted tools/list response as a committed baseline. Any change to the tool schema fails the snapshot test — forcing an intentional review before the change deploys:

// test/schema-snapshot.test.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { createHash } from 'node:crypto';
import { readFileSync, writeFileSync, existsSync } from 'node:fs';

const SNAPSHOT_PATH = 'test/schema-snapshot.json';

test('tools/list schema matches committed snapshot', async () => {
  const client = new Client({ name: 'snapshot-test', version: '1.0.0' }, { capabilities: {} });
  const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3001/mcp'));
  await client.connect(transport);

  const { tools } = await client.listTools();
  const sorted = tools.sort((a, b) => a.name.localeCompare(b.name));
  const schema = JSON.stringify(sorted, null, 2);
  const hash = createHash('sha256').update(schema).digest('hex');

  if (!existsSync(SNAPSHOT_PATH)) {
    // First run — write baseline
    writeFileSync(SNAPSHOT_PATH, JSON.stringify({ hash, tools: sorted }, null, 2));
    console.log('Schema snapshot written. Commit this file.');
    return;
  }

  const snapshot = JSON.parse(readFileSync(SNAPSHOT_PATH, 'utf-8'));
  expect(hash).toBe(snapshot.hash);
  // If this fails: review the schema change, update the snapshot, and document why.
});

await client.close();

When a tool schema change is intentional, update the snapshot file and commit it alongside the code change. The snapshot file in version control creates a permanent record of every tool schema change: when it happened, what changed, and who approved it. This is the structural defence against accidental breaking changes slipping through code review.

Multi-version servers for breaking changes

When you must make a breaking change, run both the old and new tool schema simultaneously during a migration window so existing clients have time to upgrade:

// Dual-version tool: keep the old name, add the new one, deprecate the old
server.tool(
  'search',                         // OLD name — still works
  '[DEPRECATED: use search_v2] Search docs by query',
  { query: z.string() },            // OLD schema — required string only
  async (args) => {
    // Forward to the new implementation with defaults
    return searchImpl({ query: args.query, limit: 10, format: 'text' });
  }
);

server.tool(
  'search_v2',                      // NEW name — new schema
  'Search docs by query with format and limit options',
  {
    query: z.string().min(1),
    limit: z.number().int().min(1).max(50).default(10),
    format: z.enum(['text', 'json', 'markdown']).default('text'),
  },
  async (args) => searchImpl(args)
);

Announce the deprecation in the tool description. After a migration window (typically 30-90 days for external clients, shorter for internal clients you control), remove the deprecated tool. The schema snapshot test will require a snapshot update when you add search_v2 and again when you remove search — both are intentional and documented changes.

Rolling deploys and versioning

During a rolling deploy, multiple instances of your server run simultaneously — some on the old version, some on the new. If a client session starts on the old version, subsequent requests in that session may route to a new-version instance. This creates a session-version mismatch problem.

The mitigation: use session affinity (sticky routing) during deploys. Most reverse proxies support session affinity via a cookie or the mcp-session-id header. Configure Caddy, nginx, or your load balancer to route all requests with the same mcp-session-id to the same instance for the duration of the session. AliveMCP's probe starts a new session on each probe cycle — if the probe consistently routes to a new-version instance before old-version instances are drained, the probe's tools/list hash will change at deploy time. This is expected behavior, not an incident. Monitor the probe's serverInfo.version field to confirm the deployment completed: when all instances return the new version, the rolling deploy is done.

Related questions

Further reading

• MCP server SDK — initialize handshake and serverInfo.version field
• MCP server testing — schema snapshot test for catching breaking changes in CI
• MCP server CI/CD — schema snapshot gate in the deploy pipeline
• MCP server deployment — rolling deploys and session affinity
• Schema drift in MCP tool definitions — production patterns and prevention
• MCP server health check — monitoring the initialize response across versions
• AliveMCP — uptime monitoring with tool schema change detection