Confirm the pinned SDK version before upgrading your MCP adapter
You will check which MCP SDK version your adapter resolves before upgrading, so you can tell whether an OAuth issuer check will break your login. This avoids surprises from silent dependency changes.
- Check current adapter versionKnow what you run today
- Inspect resolved SDK in lockfileConfirm the major SDK version
- Test fresh install in scratch dirFresh installs may resolve differently
- Run OAuth login on exact endpointCatch issuer mismatch before production
- Upgrade or pin, then record versionsKeep a known-good state
Why it matters
An MCP adapter's behaviour can depend on the SDK it pulls in, not only on its own version number. In pi-mcp-adapter issue #224 (opens external site), versions from 2.12.0 moved to @modelcontextprotocol/client 2.0.0-beta.5, and OAuth login to Atlassian's remote MCP failed with an issuer mismatch error (RFC 8414 section 3.3) before the browser flow started. The thread's fix was a dependency rollback in 2.16.0, not a config flag.
Steps
- Write down the adapter version you run now and the version you plan to move to. The thread reports that 2.16.0 or newer resolves the Atlassian login problem.
- Open your project lockfile and find the resolved entry for the SDK package, such as
@modelcontextprotocol/sdkor@modelcontextprotocol/client. Note which major version it resolves to. - Install the adapter in a scratch directory and check the SDK version it resolves. A fresh install can differ from an old lockfile, so do not assume the old result still holds.
- If you use OAuth, test the exact server endpoint you connect to by running the login flow once before changing production config. In the thread, the Atlassian authv2 endpoint was the one that failed on 2.12.0 and later.
- If you cannot upgrade yet, pin the adapter to a version you have verified. The thread says 2.11.0 avoids the error, but you lose features added in 2.12.0 and later, and tokens fall back to plaintext storage. Weigh that tradeoff explicitly.
- Record the adapter version and the resolved SDK version in your project notes so the next upgrade starts from a known state.
Common mistakes
- Expecting a config flag to fix a dependency-level problem. The maintainer declined a per-server skip toggle because it removes OAuth mix-up protection.
- Upgrading the adapter without checking which SDK it resolves, then debugging the wrong layer.
- Testing only in a long-lived environment with an old lockfile, which hides what a fresh install gets.
Related habit
The same check helps with other MCP servers. The brightdata-mcp thread shows that server authenticates with an account-wide API token, so keep that token in an environment variable rather than in a committed config file. That lowers the chance of it appearing in a repo or shared log.
Checklist
0 of 7 done