Compatibility & Release Testing

MCP servers depend on the MCP SDK, and SDK updates can introduce breaking changes to protocol handling, schema validation, or transport behavior. Compatibility testing runs your test suite against multiple SDK versions to ensure your server works with older clients that have not upgraded and newer clients that have. The minimum viable matrix: your pinned SDK version, the latest SDK version, and one major version back. If any version fails, you know your next release needs SDK-specific handling or a minimum SDK requirement.

Release qualification is the final gate before publishing a new server version. It runs the full test suite plus additional checks: tool catalog diff against the previous release (are there unintentional schema changes?), response size validation (no tool returns more than your documented maximum), and performance benchmarks (p95 latency per tool stays within budget). The qualification pipeline should also test the published artifact — install from npm, configure a client, and run the protocol compliance suite against the installed binary, not the source tree.

name: SDK Compatibility
on:
  schedule:
    - cron: "0 6 * * 1" # Weekly on Monday
  workflow_dispatch:

jobs:
  compat:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        sdk-version: ["1.0.0", "1.1.0", "latest"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Override SDK version
        run: npm install @modelcontextprotocol/sdk@${{ matrix.sdk-version }}
      - run: npx tsc --noEmit
      - run: npx vitest run tests/integration/ tests/e2e/

  release-qualify:
    needs: compat
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci && npm run build
      - name: Test published artifact
        run: |
          npm pack
          TARBALL=$(ls *.tgz)
          npm install -g "./$TARBALL"
          echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | mcp-server > /tmp/response.json
          node -e "const r=require('/tmp/response.json'); if(!r.result?.tools) process.exit(1)"

1. Build a version matrix Test against your pinned SDK version, the latest release, and one version back. Run weekly on a schedule plus on every release PR.
2. Add artifact testing After `npm pack`, install the tarball globally and run basic protocol checks against the installed binary. This catches packaging bugs that source-tree tests miss.
3. Gate releases on qualification Never publish without a green qualification pipeline. Include tool catalog diffing, response size checks, and the full regression suite in the gate.