	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Agentic AI > MCP Protocol > MCP Server Versioning and Backward Compatibility

MCP Server Versioning and Backward Compatibility

Author: Venkata Sudhakar

MCP servers used by production ADK agents must evolve over time - new fields get added, old parameters get renamed, tool behaviour changes. Without a versioning strategy, any breaking change breaks all connected agents immediately. A versioned MCP server lets you introduce new tool shapes while keeping old tool names working until callers migrate.

In this tutorial, you will build an MCP server that exposes both a v1 and a v2 version of the same tool using name prefixes. The v1 tool maintains its original schema. The v2 tool adds new optional fields and returns richer output. A deprecation notice in the v1 description signals callers to upgrade.

The pattern below uses tool name prefixes (v1_ and v2_) to separate versions. Both versions run in the same server process. You can sunset v1 tools by removing them in a future release once all callers have migrated to v2.

# versioned_server.py
import asyncio
import json
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

app = Server("versioned-mcp-server")

def lookup_product_v1(product_id):
    return {"id": product_id, "name": "Widget A", "price": 29.99}

def lookup_product_v2(product_id, include_stock=False):
    result = {"id": product_id, "name": "Widget A", "price": 29.99, "currency": "USD", "category": "hardware"}
    if include_stock:
        result["stock"] = 142
    return result

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="v1_get_product",
            description="[DEPRECATED - use v2_get_product] Get basic product details by ID.",
            inputSchema={
                "type": "object",
                "properties": {"product_id": {"type": "string"}},
                "required": ["product_id"]
            }
        ),
        Tool(
            name="v2_get_product",
            description="Get full product details including currency, category, and optional stock level.",
            inputSchema={
                "type": "object",
                "properties": {
                    "product_id": {"type": "string"},
                    "include_stock": {"type": "boolean"}
                },
                "required": ["product_id"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name, arguments):
    if name == "v1_get_product":
        result = lookup_product_v1(arguments["product_id"])
        return [TextContent(type="text", text=json.dumps(result))]
    elif name == "v2_get_product":
        include_stock = arguments.get("include_stock", False)
        result = lookup_product_v2(arguments["product_id"], include_stock)
        return [TextContent(type="text", text=json.dumps(result))]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

if __name__ == "__main__":
    asyncio.run(main())

The test below calls both versions to show the difference in response shape. Callers using v1_get_product continue to work unchanged while new callers use v2_get_product with richer output.

Tool name prefixes are the simplest versioning approach and work well for small tool sets. For larger servers consider URL-based versioning when using HTTP transport, or maintain a version field in the tool description that agents can read during tool discovery. Remove deprecated tools only after confirming no agents in production still call them.

Send your comments, suggestions or queries regarding this site to [email protected].