Version Your MCP Server

Agents depend on tool names, descriptions, schemas, and semantics. A “small” tool rename can break prompts, filters, approvals, and evaluations.

Prefer additive evolution

Add optional fields or new tools before removing old behavior. If semantics materially change, introduce a new tool/version rather than silently changing meaning.

Deprecate explicitly

Document what is deprecated, replacement behavior, and removal date. Keep compatibility long enough for clients to migrate.

Regression-test consumers

Run protocol contract tests and agent evaluation suites before releasing a new server version.

Separate protocol and server versions

Your server's package version is independent from the MCP specification revision it supports.