docs/docs/genai/mcp-registry/manage-versions-and-aliases.mdx
import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import { APILink } from "@site/src/components/APILink";
MCP Registry uses semantic versioning and aliases to give you precise control over which server configurations your users and agents use. This guide covers version management, status transitions, aliases, and tags.
Every MCP server version is identified by a semver string (e.g., 1.0.0, 2.0.0-beta.1). Versions are ordered by semantic version, so 2.0.0 is always considered newer than 1.9.0.
Each version has a status that controls its availability:
| Status | Description |
|---|---|
| Draft | Being prepared. Not yet available for production use. |
| Active | Ready for production use. |
| Deprecated | Still accessible but should be replaced. |
| Deleted | No longer available. |
draft → active or deletedactive → draft or deprecateddeprecated → active or deleted 1. Open the MCP server detail page.
2. Select the version you want to update from the version list.
3. Use the status controls to transition the version to a new status.
</div>
```python
import mlflow
# Promote a draft version to active
mlflow.genai.update_mcp_server_version(
name="io.github.anthropic/brave-search",
version="2.0.0",
status="active",
)
# Deprecate an older version
mlflow.genai.update_mcp_server_version(
name="io.github.anthropic/brave-search",
version="1.0.0",
status="deprecated",
)
```
</div>
The MLflow UI provides a side-by-side comparison of server versions. On the MCP server detail page, click the Compare toggle in the version list panel to select two versions and view their differences.
<div style={{ width: "90%", margin: "10px" }}>  </div>Aliases let you reference a specific version by a meaningful label (e.g., production, staging, beta) instead of a version number. This decouples your application code from specific version strings.
1. Open the MCP server detail page.
2. Click the **Edit aliases** button on a version.
3. Enter the alias name and save.
</div>
# Point "production" to version 1.0.0
mlflow.genai.set_mcp_server_alias(
name="io.github.anthropic/brave-search",
alias="production",
version="1.0.0",
)
# Move "production" to a newer version
mlflow.genai.set_mcp_server_alias(
name="io.github.anthropic/brave-search",
alias="production",
version="2.0.0",
)
```
</div>
import mlflow
version = mlflow.genai.get_mcp_server_version_by_alias(
name="io.github.anthropic/brave-search",
alias="production",
)
print(f"Production is version {version.version}")
latest AliasThe latest alias is reserved. MLflow automatically resolves it to the highest semver version among active versions. If no version is active, it falls back to the highest non-deleted version.
import mlflow
latest = mlflow.genai.get_latest_mcp_server_version(
name="io.github.anthropic/brave-search",
)
import mlflow
mlflow.genai.delete_mcp_server_alias(
name="io.github.anthropic/brave-search",
alias="staging",
)
Tags are key-value pairs you can attach to servers and versions for organization and filtering.
import mlflow
# Set a tag on the server
mlflow.genai.set_mcp_server_tag(
name="io.github.anthropic/brave-search",
key="team",
value="platform",
)
# Delete a tag
mlflow.genai.delete_mcp_server_tag(
name="io.github.anthropic/brave-search",
key="team",
)
import mlflow
# Set a tag on a specific version
mlflow.genai.set_mcp_server_version_tag(
name="io.github.anthropic/brave-search",
version="1.0.0",
key="release-notes",
value="Initial release with web search support",
)
# Delete a version tag
mlflow.genai.delete_mcp_server_version_tag(
name="io.github.anthropic/brave-search",
version="1.0.0",
key="release-notes",
)
import mlflow
# Versions must be in draft or deprecated status before deletion
mlflow.genai.update_mcp_server_version(
name="io.github.anthropic/brave-search",
version="1.0.0",
status="deprecated",
)
mlflow.genai.delete_mcp_server_version(
name="io.github.anthropic/brave-search",
version="1.0.0",
)