MCP Server Versioning Guidelines Proposal

[olaservo]

Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

I'd like to propose adding some simple guidelines for server versioning to the MCP supporting documentation.

These guidelines would help standardize how server versions are reported during initialization, making it easier for clients to understand and check for compatibility.

Real examples of why this is needed:

The Server version is what hosts/clients like Claude Desktop or Inspector see during initialization, for example if we're connecting to @modelcontextprotocol/server-everything:

Claude client logs shows 1.0.0:

Message from server: {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2024-11-05","capabilities":{"prompts":{},"resources":{"subscribe":true},"tools":{},"logging":{}},"serverInfo":{"name":"example-servers/everything","version":"1.0.0"}}}

...while the semantic version in package.json is 0.6.2 (and the published package is now using CalVer 2025.4.28).

(Edit: I found out that Claude Desktop doesn't log or show the server version anymore in the UI, so this log was taken from March.)

Referencing the Server version is convenient as a host/client since that way the client doesn't need to understand how to parse various package metadata from npm, pip, etc. However, I don't see the version being used consistently yet which makes it somewhat useless when it comes to understanding whether a server has changed, and what type of change. This matters if something stops working, either intentionally or not, since then its easier to debug whether the issue is tied to a specific released version.

My proposal is that the MCP Server version should always match the semantic version of the associated package when applicable. This could be worded as:

## Server Versioning
When configuring the server's version information during initialization, the following practices are recommended:

### Version Format
- **Use Semantic Versioning (SemVer)**: Server versions SHOULD follow the format of `MAJOR.MINOR.PATCH` as defined in [Semantic Versioning 2.0.0](https://semver.org/).
- **Increment appropriately**: Increment the MAJOR version for incompatible API changes, MINOR version for backward-compatible functionality additions, and PATCH version for backward-compatible bug fixes.

### Version Alignment
- **Maintain consistency with package versions**: The server version reported in `serverInfo.version` SHOULD align with the version of the distributed package when possible (e.g., in package.json, pyproject.toml, etc.).
- **Automate version extraction**: Consider extracting the version programmatically from package metadata rather than hardcoding it to prevent inconsistencies.