MCP 2026-07-28 协议大升级：Breaking Changes 全解析与迁移实战指南

旧模型（stdio + SSE 双通道）：

  Client ──stdio──> MCP Server Process
  Client ──SSE────> MCP HTTP Server (独立进程)

新模型（Streamable HTTP 统一端点）：

  Client ──HTTP POST──> /mcp (单一端点，支持请求/响应 + 流式推送)

{
  "event": "mcp_server_errors",
  "timestamp": "2026-07-28T10:00:00Z",
  "errors": [
    {
      "serverName": "my-postgres-tools",
      "configPath": "~/.claude/mcp_servers.json",
      "errorType": "STARTUP_FAILURE",
      "message": "Failed to connect to PostgreSQL: connection refused",
      "severity": "ERROR"
    },
    {
      "serverName": "legacy-filesystem-tools",
      "configPath": "~/.claude/mcp_servers.json",
      "errorType": "SKIPPED",
      "message": "Transport type 'stdio' is deprecated, server skipped",
      "severity": "WARNING"
    }
  ]
}

# old_server.py - 旧版 stdio MCP Server
import json
import sys
from mcp.server.stdio import stdio_server

@stdio_server()
async def serve():
    async with asyncio.TaskGroup() as tg:
        # 在 stdio 模式下，通过标准输入输出通信
        # Server 进程由 Claude Desktop 启动和管理
        pass

async def handle_tool_call(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments.get("city", "Beijing")
        return {"temperature": 28, "city": city}
    elif name == "calculate":
        expression = arguments.get("expression", "")
        try:
            result = eval(expression)
            return {"result": result}
        except Exception as e:
            return {"error": str(e)}

# new_server.py - 新版 Streamable HTTP MCP Server
import asyncio
import json
from mcp.server.streamable_http import streamable_http_server
from mcp.types import Tool, TextContent

# 定义工具列表
TOOLS = [
    Tool(
        name="get_weather",
        description="获取指定城市的天气信息",
        inputSchema={
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称"
                }
            },
            "required": ["city"]
        }
    ),
    Tool(
        name="calculate",
        description="执行数学表达式计算",
        inputSchema={
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "数学表达式，如 '2 + 3 * 4'"
                }
            },
            "required": ["expression"]
        }
    ),
]

async def handle_request(method: str, params: dict | None) -> dict | None:
    """处理 MCP JSON-RPC 请求（无状态）"""
    if method == "initialize":
        return {
            "protocolVersion": "2026-07-28",
            "capabilities": {
                "tools": {"listChanged": False}
            },
            "serverInfo": {
                "name": "weather-calculator",
                "version": "2.0.0"
            }
        }

    elif method == "tools/list":
        return {"tools": TOOLS}

    elif method == "tools/call":
        tool_name = params.get("name") if params else None
        arguments = params.get("arguments", {}) if params else {}

        if tool_name == "get_weather":
            city = arguments.get("city", "Beijing")
            return {
                "content": [
                    TextContent(
                        type="text",
                        text=json.dumps({
                            "city": city,
                            "temperature": 28,
                            "condition": "sunny",
                            "humidity": 65
                        }, ensure_ascii=False)
                    )
                ]
            }

        elif tool_name == "calculate":
            expression = arguments.get("expression", "")
            try:
                # 注意：生产环境应使用安全的表达式解析器
                result = eval(expression, {"__builtins__": {}}, {})
                return {
                    "content": [
                        TextContent(
                            type="text",
                            text=f"计算结果: {expression} = {result}"
                        )
                    ]
                }
            except Exception as e:
                return {
                    "content": [
                        TextContent(
                            type="text",
                            text=f"计算错误: {str(e)}"
                        ),
                        TextContent(
                            type="text",
                            text="请检查表达式格式是否正确"
                        )
                    ],
                    "isError": True
                }

    return None

async def main():
    """启动 Streamable HTTP MCP Server"""
    server = streamable_http_server(
        host="0.0.0.0",
        port=8765,
        endpoint="/mcp",
        request_handler=handle_request,
    )
    print("MCP Streamable HTTP Server 启动于 http://localhost:8765/mcp")
    print("支持的协议版本: 2026-07-28")
    print("可用工具: get_weather, calculate")
    await server.serve()

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

{
  "mcpServers": {
    "weather-calculator": {
      "type": "streamable-http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

async def main():
    # 同时启动 stdio 和 HTTP 端点
    http_server = streamable_http_server(
        host="0.0.0.0",
        port=8765,
        endpoint="/mcp",
        request_handler=handle_request,
    )
    stdio_task = asyncio.create_task(stdio_serve(handle_request))

    await http_server.serve()

async def handle_request(method: str, params: dict | None) -> dict:
    if method == "initialize":
        client_version = params.get("protocolVersion", "2024-11-05")
        if client_version.startswith("2024"):
            # 兼容旧版客户端：启用有状态模式
            return {
                "protocolVersion": "2024-11-05",
                "capabilities": {"statefulSession": True},
                "serverInfo": {"name": "compatible-server", "version": "2.0.0"}
            }
        else:
            # 新版客户端：无状态模式
            return {
                "protocolVersion": "2026-07-28",
                "capabilities": {"tools": {"listChanged": False}},
                "serverInfo": {"name": "compatible-server", "version": "2.0.0"}
            }

{
  "workflowSizeGuideline": {
    "maxConcurrentTools": 5,
    "maxPayloadSize": "10MB",
    "recommendedBatchSize": 3
  }
}