Migrate servers to MCP Python SDK v2 and remove the mcp[cli]<2.0.0 cap (48 servers)

[scottschreckengaust]

Summary

PR #4360 added mcp[cli]>=...,<2.0.0 to 44 servers as a stopgap for #4354, pinning the
ecosystem to SDK 1.x. This issue tracks removing that cap by porting the servers to v2.

SDK 2.0.0 removed mcp.server.fastmcp (it is gone, not deprecated) and renamed
FastMCP -> MCPServer. Every capped server would crash at import under 2.x, so the cap
is load-bearing and cannot simply be dropped.

Actual scope: 48 servers / 246 files

Larger than PR #4360's pyproject count suggests. Four servers (amazon-keyspaces,
amazon-translate, aws-iot-sitewise, ecs) declare the standalone fastmcp package
and import mcp.server.fastmcp, so they are affected too and can't be set aside as
"different dependency."

API surface

Verified by importing from an installed mcp 2.0.0 rather than reading the migration
guide. All seven v1 import forms present in src/ move under mcp.server.mcpserver:

v1 import	files	v2 import
from mcp.server.fastmcp import Context	143	from mcp.server.mcpserver import Context
from mcp.server.fastmcp import Context, FastMCP	45	from mcp.server.mcpserver import Context, MCPServer
from mcp.server.fastmcp import FastMCP	41	from mcp.server.mcpserver import MCPServer
from mcp.server.fastmcp.tools import Tool	10	from mcp.server.mcpserver.tools import Tool
from mcp.server.fastmcp.prompts import Prompt	5	from mcp.server.mcpserver.prompts import Prompt
from mcp.server.fastmcp.exceptions import ToolError	3	from mcp.server.mcpserver.exceptions import ToolError
from mcp.server.fastmcp.server import Context	1	from mcp.server.mcpserver.server import Context

Constructor kwargs (instructions, dependencies), the mcp.tool() decorator, and
mcp.run() are unchanged. For a stdio server the migration is effectively an import
rename. No file in src/ uses the 3-parameter Context[ServerSessionT, ...] form, so
that v2 delta doesn't apply here.

Approach

Per-server: rename imports -> bump cap to >=2.0.0,<3.0.0 -> uv lock -> run that
server's own test suite. Rename and cap bump must land atomically per server, since
v2-only imports break under a 1.x resolution.

Stateless / streamable-HTTP / cache-hint adoption is out of scope — it matters for
remote-deployed servers and is a separate per-server decision.

Rejected: a try/except ImportError shim supporting both 1.x and 2.x. It would add
dual-path complexity to 48 servers for a transitional benefit, and the repo pins via
lockfiles anyway.

Needs individual review

• Heaviest surface — amazon-bedrock-agentcore (33 files), aws-dataprocessing (32),
  aws-serverless (26), aws-healthomics (25), eks (16), aws-iot-sitewise (15),
  aws-transform (15).
• stateless_http= — aws-api-mcp-server passes it to the constructor; in v2 it moves
  to run(). The one confirmed non-mechanical change. (Not among the 48 — it uses the
  standalone fastmcp package.)
• String monkeypatch targets — 3 files patch 'mcp.server.fastmcp.FastMCP' as a
  string. Both halves must be renamed together; rewriting only the module yields
  mcp.server.mcpserver.FastMCP, which doesn't exist and fails at patch time rather than
  import time.
• Standalone fastmcp servers — the 4 above need a dependency decision alongside the
  rename.

Separate latent bug

ecs-mcp-server imports mcp.server.fastmcp but declares no mcp dependency at all
(only fastmcp>=3.0.0) — it receives mcp transitively. Worth fixing independently of
this migration.

Plan

First server + tooling, then the rest in follow-up PRs (individually or batched), each
gated on its own test suite so one failure doesn't block the others.

• lambda-tool-mcp-server + scripts/migrate-mcp-v2.py codemod
• Remaining 47 servers
• ecs-mcp-server missing mcp dependency (separate)

Related: #4354, #4360, #2533.

[scottschreckengaust]

Note: is <3.0.0 the right ceiling?

Raising this separately from the first migration PR (#4449), since it's a dependency-policy
question that should be answered uniformly rather than settled inside a port.

The repo's own convention argues against capping. Across 402 dependency specs in
src/*/pyproject.toml, only 62 (15%) carry an upper bound — and mcp is 45 of those.
Excluding mcp, it's roughly 4%:

dep	bounded / total
pydantic	1 / 56
boto3	2 / 54
loguru	1 / 52
botocore	0 / 17
mcp	45 / 53

pydantic and boto3 can break in a major just as easily and aren't capped. So <2.0.0
isn't house style — mcp is the exception, introduced by #4360. Worth deciding whether
that's intentional, because nobody has written down why mcp is special, and the next
contributor adding a dependency has no rule to follow.

What's genuinely different about mcp:

1. Demonstrated major-version breakage with total loss of function — 1.x -> 2.x deleted a
   module, and the failure is ModuleNotFoundError before initialize, which users see as
   an opaque -32000 connection error ((aws-pricing-mcp-server, aws-serverless-mcp-server): fail to start with mcp SDK 2.0.0 — ModuleNotFoundError: No module named 'mcp.server.fastmcp' #4354). One data point, but severe, and the only
   major transition in the package's history.
2. uv.lock does not protect users. The lock isn't shipped in the wheel
   (packages = ["awslabs"]), so uvx ...@latest — which 57 READMEs recommend — resolves
   fresh from the pyproject.toml spec every time. The declared cap is the only guard.
   (This corrects the "we pin via lockfiles anyway" reasoning: lockfiles cover contributors
   and CI, not end users.)
3. Asymmetric cost: cap too tight -> a mechanical PR to widen. No cap and 3.0 breaks ->
   every server broken for users until a fix ships.

Options:

• Keep capping mcp only (current, implicit). Defensible on the above, but undocumented.
• Drop the cap, matching the repo's 96% norm; accept an emergency fix if 3.0 breaks.
• Cap + CI canary — a scheduled job installing unpinned mcp and running the suites, so
  breakage surfaces before users hit it. This makes the cap a safety net rather than a
  permanent tax, and is the option I'd suggest.

Whichever is chosen, it should be recorded somewhere contributors will find it. #4449 keeps
>=2.0.0,<3.0.0 to preserve the #4360 status quo, so this can be decided independently.

[scottschreckengaust]

Fleet rollout pushed: feat/mcp-v2-fleet (no PR yet)

Branch: feat/mcp-v2-fleet — 3 commits, a superset of #4449's branch (same two commits at its base, plus the fleet commit 7bcbb4f0). Pushed to record the work; deliberately no PR opened and #4449 left as-is.

This closes out the "Remaining 47 servers" checkbox in the plan above, with three exceptions noted below.

Result

	Count
Servers declaring mcp>=2.0.0,<3.0.0	46
↳ full suite passes	37
↳ failures that reproduce identically on unmodified origin/main	9
Blocked upstream, deliberately left on v1	3
No mcp SDK dependency to bump	4
Unexplained regressions	0

370 files, 273 of them Python. Every suite was run against unmodified origin/main before any failure was called a regression.

Two v2 changes not in the API table above

Both were found by running suites, not by reading the migration guide, and both share the same trap: construction still works, reads/assignment break.

1. MCPError constructor flattened. v2 takes the fields directly instead of a prebuilt ErrorData:

raise McpError(ErrorData(code=INTERNAL_ERROR, message=msg))   # v1
raise MCPError(code=INTERNAL_ERROR, message=msg)              # v2

Reads of .error / .code / .message are unchanged, so only the raise sites break — with a TypeError, at raise time, not import time. 11 files across mssql, oracle, postgres and aws-for-sap-management. Automated via AST (the inner call spans lines and message= routinely holds an f-string with its own parens, so regex isn't safe here). The now-dead ErrorData import is pruned too, since F401 is on fleet-wide.

2. Transport settings moved off Settings onto run(). v2's Settings has 8 fields, down from 17 — port, host, stateless_http, sse_path and friends are now run() keywords:

mcp.settings.port = args.port                  # v1
mcp.run(transport="sse")
mcp.run(transport="sse", port=args.port)       # v2

Pydantic intercepts the removed-field assignment, so the symptom is ValueError: "Settings" object has no field "port", not AttributeError. This is the same delta the issue flagged for aws-api-mcp-server's stateless_http=; it also hit well-architected-security-mcp-server. The codemod reports these rather than rewriting them, because moving an argument across a call boundary usually needs a matching test change.

Also: MCPServer.get_context() is gone (build Context(mcp_server=...) directly) and create_connected_server_and_client_session is gone (only create_client_server_memory_streams remains).

Blocked: 3 servers cannot migrate yet

aws-api-mcp-server, billing-cost-management-mcp-server and dynamodb-mcp-server are left on v1 with an explanatory comment. fastmcp 3.x depends on fastmcp-slim, which pins mcp>=1.24.0,<2.0, so mcp>=2.0.0 is unsatisfiable for them — not a code problem. dynamodb inherits the constraint through awslabs-aws-api-mcp-server.

Verified with uv pip compile: fastmcp 3.4.6 fails against mcp 2.0.0; only the unreleased fastmcp 4.0.0b1 resolves. Revisit when fastmcp 4.0 ships — that is the single blocker for these three.

The codemod hard-errors if you name one via --server, since a half-migrated blocked server is broken against both SDKs. Remove them from BLOCKED_SERVERS in scripts/migrate-mcp-v2.py once 4.0 is out.

One accidentally-passing test, worth a second opinion

aws-transform-mcp-server's PROFILE_SELECTION_REQUIRED fallback test passed under v1 only by accident: v1's elicit_with_validation ended with raise ValueError(...), which a bare AsyncMock triggered and an except Exception swallowed into the fallback path. v2 correctly returns CancelledElicitation instead, so the test started failing — the test had never declared the non-elicitation client its own assertion requires.

I fixed the setup, not the assertion, matching TestSelectProfileFallback. Flagging it because it's a behavior question, not a mechanical one: the assertion was always the intended one, but v1 never actually exercised the path it claims to.

New tooling: scripts/verify-mcp-v2-locks.py

uv run resolves from uv.lock, not pyproject.toml. A lock predating a cap change keeps installing the old SDK — so the suite passes against v1 while the manifest claims v2. A green run that proves nothing. This bit during the rollout and is invisible without a cross-check:

python3 scripts/verify-mcp-v2-locks.py            # report
python3 scripts/verify-mcp-v2-locks.py --strict   # exit 1 on mismatch

Worth wiring into CI regardless of how this migration lands.

Picking this up

git fetch origin && git checkout feat/mcp-v2-fleet
python3 scripts/verify-mcp-v2-locks.py     # expect: every server declaring mcp>=2.0.0 has a 2.x lock
python3 scripts/migrate-mcp-v2.py          # expect: no work remaining (idempotent)

Verified before the push: 2366 files compile; codemod idempotent; ruff-check / ruff-format clean over all 273 changed files; the only residual v1 API references are inside the 3 deliberately-blocked servers. Replaying the codemod against pristine origin/main reproduces #4449's branch byte-for-byte on all 4 files.

The 9 baseline-confirmed pre-existing failures (unrelated to this work, listed for whoever runs the suites): amazon-kendra-index (5), amazon-mq (2), amazon-qbusiness-anonymous (1), amazon-sns-sqs (1), aws-dataprocessing (2), aws-pricing (3), ccapi (2), elasticache (env), timestream-for-influxdb (1).

Open decisions for a reviewer — none of these are blocked on more investigation, they're judgement calls:

1. How to land it. One 370-file PR, or per-server PRs off this branch? The commit is already split so src/<server>/ slices cleanly. The issue's plan says follow-up PRs "individually or batched" — this branch is the batched form, and 45 servers in one review is a lot.
2. Relationship to fix(lambda-tool-mcp-server): migrate to mcp SDK v2, remove <2.0.0 cap, add rollout codemod #4449. This branch contains fix(lambda-tool-mcp-server): migrate to mcp SDK v2, remove <2.0.0 cap, add rollout codemod #4449's commits, so merging fix(lambda-tool-mcp-server): migrate to mcp SDK v2, remove <2.0.0 cap, add rollout codemod #4449 first is a clean fast-forward. Alternatively fix(lambda-tool-mcp-server): migrate to mcp SDK v2, remove <2.0.0 cap, add rollout codemod #4449 becomes redundant and closes.
3. ecs-mcp-server's missing mcp dependency (third checkbox above) is untouched here — still worth fixing separately.
4. uv.lock churn: 45 locks, ~9.4k lines. Unavoidable given the cap change, but it dominates the diff.

🤖 Generated with Claude Code

[scottschreckengaust]

Fleet PR opened: #4452 (draft) — 46 servers, MERGEABLE. Supersedes the branch-only note above.

Two decisions from that comment are now settled in the PR: it is the batched form (one PR, sliceable per-server if a reviewer prefers), and it contains #4449's commits, so merging #4449 first is a clean fast-forward.

Still open: ecs-mcp-server's missing mcp dependency (third checkbox above) remains untouched and separate.