Pin MCP server dependencies so new SDK releases cannot break startup
You will pin the versions your MCP servers launch with, so a new SDK or package release cannot silently break startup. This keeps working setups stable and gives you a known-good fallback when an upstream release goes bad.
- Inventory launchesFind every server that runs with npx or uvx without a fixed version.
- Pin tested versionUse a version a maintainer or your own test confirmed works.
- Pin transitive SDKFix the shared dependency that the server imports.
- Restart and verifyStart a fresh session and confirm tools load.
- Review on scheduleUpgrade deliberately, testing before production use.
Why it matters
Several MCP servers launch with floating versions. The awslabs.eks-mcp-server package declares mcp[cli]>=1.11.0, so when the mcp 1.19.0 release landed on October 24, 2025, the server crashed on startup with InvalidSignature: CallToolResult cannot be used in Union or Optional types. The issue was closed as NOT_PLANNED with no fix in the thread, as described in the awslabs issue (opens external site). The lesson is that @latest or an unpinned dependency means your next launch can differ from your last one.
Steps
-
List every MCP server in your client config and note how each one is launched, for example
npx -y <package>oruvx <package>@latest. Anything without an explicit version is a candidate for pinning. -
Pin the server package to a version you have tested. For exa-mcp-server, the maintainer confirmed in the thread that
exa-mcp-server@3.0.5works on stdio, so use that version instead of the unversioned name. -
Where the server has a transitive dependency that broke it, pin that dependency too. The awslabs thread suggested launching with
uvx --with mcp==1.18.0as a workaround. This was suggested in the thread and not confirmed tested there, so treat it as a starting point and verify it locally:
"awslabs.eks-mcp-server": {
"command": "uvx",
"args": [
"--with",
"mcp==1.18.0",
"awslabs.eks-mcp-server@latest",
"--allow-write",
"--allow-sensitive-data-access"
],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" }
}
Note that the example still uses @latest for the server itself. Replace it with a fixed version once you have picked one, and drop the write and sensitive-data flags unless you need them.
-
Restart the client and confirm the server starts and lists its tools. Do this after every pin change.
-
Record the pinned versions in your team's config or notes so the next person knows why they are set.
-
Review pins on a schedule, not on every release. When you upgrade, test on a non-production client first.
Common mistakes
- Pinning only the top-level server but not the SDK it imports, which leaves the same breakage in place.
- Using
@latestin a config that other people copy, so the unpinned launch spreads. - Assuming a pin is permanent. Old versions can lose tools or fixes, as the exa thread showed with 2.0.9 missing some tools.
- Keeping extra write or sensitive-data flags in a pinned config after the need has passed.
Checklist
0 of 8 done