feat(deps): support mcp 2 alongside mcp 1

Merged
GL
9d ago
+287-358

What

The SDK now runs on mcp 2 as well as mcp 1. pyproject.toml allows mcp>=1.30.0,!=2.0.*,!=2.1.*,<3.0.0 and the lockfile pins mcp 2.3.0. This replaces the Dependabot bump in #208, which cannot merge as is: on mcp 2.3.0, every fetch_tools() and tool call on main fails.

  • stackone_ai/tools.py: _mcp_http is httpx2 when mcp 2 is installed and httpx otherwise, and the MCP transport client, timeouts and error types come from it. GET /accounts stays on httpx.
  • The transport yields two streams on both majors (mcp 2 yields two, mcp 1 three).
  • _mcp_field reads model fields by their snake_case name (mcp 2) or wire name (mcp 1): inputSchema, nextCursor, structuredContent, isError.
  • A failed POST other than a 404 raises HTTPStatusError with its status and body, as mcp 1 does. mcp 2 would turn it into a JSON-RPC error with neither. A 404 is still handed to mcp, which reports a lost session.
  • call_mcp_tool passes CallToolRequest to send_request directly, which both majors accept.
  • CI runs the suite a second time against mcp 1.30.0, the oldest version the range allows.

Why, with evidence

  • main on mcp 2.3.0: ToolsetLoadError: ... ValueError: not enough values to unpack (expected 3, got 2) on every list and call, because streamable_http_client changed its yield.
  • mcp 2.0.x and 2.1.x carry four published advisories that 2.2.0 fixes (GHSA-w4fh-qvv9-3v23, GHSA-5h93-6whr-6q8j, GHSA-rwrf-2pqf-9j8j, GHSA-84m7-p3x7-pcfv). Below 1.30.0 the same advisories apply, so the range excludes both.

How verified

  • ruff check, ruff format --check, ty check stackone_ai examples: clean.
  • pytest: 879 passed on mcp 2.3.0 (locked), on 2.2.0 and on 1.30.0 (uv run --with).
  • scripts/validate.sh: PASS 6/6 (examples, conformance --strict-schema, SDK smoke, Pydantic AI 1.x and 2.x, Google ADK plugin).
  • Demo against the repo's MCP mock (tests/mocks/serve.ts): list two accounts (one valid, one the mock refuses with 400), then call a listed tool and an unknown one.
Runlist acc1list refused accountcall listed toolcall unknown tool
main, mcp 1.30.03 toolsStackOneAPIError 400 with server bodyokStackOneAPIError "Unknown tool"
main, mcp 2.3.0ToolsetLoadError (unpack)ToolsetLoadError (unpack)ToolsetLoadErrorToolsetLoadError
this PR, mcp 2.3.03 toolsStackOneAPIError 400 with server bodyokStackOneAPIError "Unknown tool"
this PR, mcp 1.30.03 toolsStackOneAPIError 400 with server bodyokStackOneAPIError "Unknown tool"

Good citizen

Retry counts, backoff, Retry-After handling, timeouts and concurrency are unchanged. TLS still uses the same verified SSL context. No new network calls and no new dependencies: httpx2 is imported only when mcp 2, which requires it, is installed.

Gates (head 5429c2b)

GateResult
Forgemeter on own diff: 7 comment lines, longest block 2, 0 copies; two stale comments fixed, no other findings
Security scan (security and dependency reviewers)no Critical, High or Medium; uv lock --check ok; no OSV/GHSA entries for the new versions
Codex security passno new findings. Noted a pre-existing one: error bodies are buffered without a size cap (_buffer_error_body, unchanged from main)
Aikido open issues0 critical, 0 high; the 1 medium and 2 low are pre-existing and outside the changed lines
/security-review checklistsecrets and injection pass; the service sections (routes, DB, webhooks) do not apply to a library
/code-review10 findings, none needing a change: notification and 404 handling match mcp 1, the mcp 1 lane imports httpx not httpx2, Tool.inputSchema is a required dict on both majors, the toolset.py items belong to #261
Codex review (e11c60f)no bugs; its two test gaps are closed in 5429c2b

Merge order

This branch is built on #261 and includes its commits, so merge #261 first. This PR then supersedes #208, which can be closed.

Post-merge validation

  • release-please opens a feat (minor) release PR; after it publishes, install the release with mcp 2.3.0 and with mcp 1.30.0 and run the quickstart example against a real key.
  • Then check that downstream consumers of the SDK resolve and pass with the new release before bumping them.

Requested by guillaume@stackone.com in Slack (repo audit thread).

šŸ¤– Generated with Claude Code


Summary by cubic

The SDK now runs on mcp 2 as well as mcp 1, so installs next to packages that require mcp 2 no longer conflict while projects pinned to mcp 1 keep resolving. On main, mcp 2 made every fetch_tools() call and tool invocation fail with a ToolsetLoadError.

  • The range is now mcp>=1.30.0,!=2.0.*,!=2.1.*,<3.0.0 and the lockfile pins mcp 2.3.0; 2.0.x and 2.1.x are excluded because they carry four published advisories.
  • MCP requests use the HTTP library the installed mcp takes: httpx on mcp 1, httpx2 on mcp 2. GET /accounts stays on httpx.
  • Tool definitions and results read their fields by snake-case name on mcp 2 and wire name on mcp 1 (inputSchema, nextCursor, structuredContent, isError); on mcp 2 the wire names silently read every failed call as a success.
  • Non-404 failed POSTs raise HTTPStatusError with their status and body, as mcp 1 does; mcp 2 would otherwise turn them into a JSON-RPC error carrying neither. A 404 is still left to mcp as a lost session.
  • CI runs the suite a second time against mcp 1.30.0, the oldest allowed version.
  • This builds on the shared MCP plumbing refactor and supersedes the earlier Dependabot bump, which cannot merge as is.