refactor: share the MCP session and end-user retry plumbing

Closed
GL
9d ago
+102-113

What

  • fetch_mcp_tools and call_mcp_tool share a new _run_mcp_session(endpoint, headers, timeout, work): it opens the transport, builds and initializes the ClientSession under the anyio.fail_after deadline, runs work(session), and maps any Exception through _raise_mcp_failure. Each function now holds only its own exchange (paginated tools/list, or one tools/call).
  • The "retry once with the looked-up end user" logic, written three times (per-account listing in fetch_tools, the search/execute listing, StackOneMcpTool.execute), is now retry_for_end_user(call, accounts, look_up).

Why

Both blocks were copied line for line, so a fix to one (deadline scope, failure mapping, retry rules) had to be made in two or three places. The next change to the MCP client (reusing a session across calls) touches exactly this code, so it goes on top of one copy instead of two.

Behaviour

None intended. Points checked:

  • The deadline still covers transport entry, session entry, initialize and the operation.
  • Only Exception is mapped, so KeyboardInterrupt and SystemExit still propagate.
  • The retry fires only for a 400 naming an account that was sent without a recorded end user, at most once, and only when the lookup finds the end user. The single-account sites used to rely on _look_up_end_user to check the refusal; the helper checks it first with the same predicate.
  • Headers are rebuilt on the retry (_build_mcp_headers runs again inside the lambda), as before.
  • The mcp import guard is kept in the shared helper.

How verified

  • uv run ruff check ., uv run ruff format --check ., uv run ty check stackone_ai examples: clean.
  • uv run pytest (Python 3.13, MCP mock via pnpm): 871 passed, the same count as main; the end-user retry tests in tests/test_end_user_id.py and the mocked-session tests in tests/test_fetch_tools.py run unchanged.

Gates (head e53d02b)

GateResult
Repo skillsnone in repo
/forge:forgeran on 3b8576f: one duplicate comment removed (9b55941); re-run on e53d02b: +40 -107, 10 comment lines, 0 copies
Security scansecurity-reviewer agent: no finding at confidence 70 or above. Aikido: 31 open issues on main (lockfile CVEs, workflow SAST, one old test-fixture secret), none on lines this PR changes
Codex securityclean on 9b55941 (job 4de47dd5) and e53d02b (job b2f55e81)
/security-reviewran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK
/code-reviewmedium on 9b55941, 5 candidates. Fixed 1: the end-user refusal check now lives only in retry_for_end_user, so the look-up no longer repeats it. Declined 4: the unguarded mcp.types import in call_mcp_tool is unchanged from main, the session was already untyped for ty (the import carries an unresolved-import ignore), the unprefixed helper name matches is_end_user_refusal and build_request_headers, and the one-element account list keeps one helper for both paths
CIgreen on e53d02b: 10 pass, 3 skipped
Unresolved review threads0

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

šŸ¤– Generated with Claude Code


Summary by cubic

Shares the MCP session plumbing and the end-user retry logic, previously duplicated across two and three call sites respectively. No behavior change: deadline scope, failure mapping, retry eligibility, and header rebuild on retry all work as before.

Refactor

  • fetch_mcp_tools and call_mcp_tool now delegate to a shared _run_mcp_session helper; each keeps only its own exchange (tools/list pagination or one tools/call).
  • The retry-once-with-looked-up-end-user logic is now retry_for_end_user, used by the per-account listing, search/execute listing, and tool execution paths; the refusal check lives only there.
  • The merge from main carried its edits into the shared helper: tools/list pagination, the dropped ty ignores, and the shared SSL context.
  • The mcp import guard stays in the shared helper, so a missing optional dependency is still surfaced as a ToolsetConfigError.
  • The pagination test now asserts the list_tools params on each call, so a regression to the old positional cursor argument fails.