Skip to content
⚠️ Before You Start
Risk: High
Duration: 1-3 days per server including canary
Last Validated: Not yet validated (draft)
Kind: Runbook
Risk Note: High (breaking changes in transport, sessions and auth affect every connected agent)

Upgrade an MCP server to a new protocol revision or SDK major version

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-27). Author: Sivaraj · dry-run: James · sign-off: Prasanna. Work items: AGT-10-T13, AGT-10-T14, AGT-10-T15, AGT-10-T16.

1. Summary

When moving servers from Python SDK v1 to v2, adopting the 2026-07-28 stateless revision, or when a client host stops supporting an older revision.

Risk: High (breaking changes in transport, sessions and auth affect every connected agent). Typical duration: 1-3 days per server including canary.

2. When to use and when not to

Use it when: When moving servers from Python SDK v1 to v2, adopting the 2026-07-28 stateless revision, or when a client host stops supporting an older revision.

Do not use it when: to be written by the author.

3. What you must know first

  • 2026-07-28 removes sessions, the initialize handshake, ping and SSE resumability, and adds server/discover
  • Tasks moved to an official extension and Roots, Sampling and Logging are deprecated
  • Dynamic Client Registration is deprecated in favour of Client ID Metadata Documents
  • SDK v2 changes class names, constructor argument order and where transport options live
  • Servers needing cross-call state must pass explicit handles as tool arguments

4. Prerequisites and access

  • Inventory of connected clients and the revisions they use
  • Contract tests that run against the server from at least two client versions
  • Blue-green or revision-based deployment on Container Apps
  • Read the SDK migration guide and the protocol changelog

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. List every feature the server uses that the changelog removes or deprecates.
  2. Upgrade the SDK on a branch and fix imports, constructor keywords and run() options.
  3. Replace session-based state with explicit handles where needed.
  4. Run contract tests from old and new client versions.
  5. Deploy as a new revision with 0% traffic and run the smoke test against its URL.
  6. Shift 10% of traffic and watch error rates and 4xx codes for 1 hour.
  7. Shift the rest when error rates match the old revision.
  8. Update the catalog entry with the new supported revisions.
  9. Rollback: shift traffic back to the previous revision and keep it for at least 7 days.

Draft snippet: Contract tests against two client SDK versions

name: mcp-contract-tests
on:
  pull_request:
    paths: ["mcp_servers/**"]
jobs:
  contract:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        client_sdk: ["mcp>=1.30,<2", "mcp>=2,<3"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install "${{ matrix.client_sdk }}" -r mcp_servers/requirements-test.txt
      - run: pytest mcp_servers/tests/contract -q
        env:
          MCP_SERVER_URL: ${{ vars.SANDBOX_MCP_URL }}

Snippets to add:

  • snippets/pipelines/mcp-contract.yml: CI matrix running contract tests from two client SDK versions (yaml)
  • snippets/ops/mcp-canary.sh: Container Apps traffic split for canary (bash)
  • snippets/docs/mcp-upgrade-impact.md: Upgrade impact checklist from the changelog (markdown)

6. Monitoring and alerts

Signal Alert when Action
Error rate on the new revision Higher than the old revision by 2 points for 15 minutes Shift traffic back and investigate
UnsupportedProtocolVersion errors Any after the canary starts Identify the client and keep earlier revision support

7. Rollback

To be written by the author: how to undo each risky step.

8. Known issues and fixes

Symptom Likely cause Fix
Instructions text ends up in the server title v1 positional constructor arguments used with v2 Pass all arguments after the name by keyword
Requests fail with 'Task group is not initialized' Mounted app lifespan does not run the session manager Enter mcp.session_manager.run() in the host lifespan
Older clients fail after upgrade Client depends on sessions or initialize Keep earlier revision support until the client upgrades
Long-running tool results lost SSE resumability removed in 2026-07-28 Use the tasks extension or make clients re-issue requests

9. AWS and open-source equivalents

On AWS, AgentCore Gateway and Runtime manage protocol support for hosted servers; check their supported revisions. Open-source servers follow the same SDK migration guides on any host.

10. Validation record

Pending. Planned dry-run scenario: A second engineer upgrades the sandbox demo server from SDK v1 to v2 and runs a canary with two test clients on different SDK versions. Pass: contract tests pass for both, the canary shows no error increase and rollback restores the old revision in under 5 minutes.

11. Sources