Skip to content

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

Closed
glebedel wants to merge 5 commits into
mainfrom
s2d2/audit-dedupe-mcp-plumbing
Closed

glebedel wants to merge 5 commits into
mainfrom
s2d2/audit-dedupe-mcp-plumbing

Conversation

@glebedel

@glebedel glebedel commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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)

Gate Result
Repo skills none in repo
/forge:forge ran on 3b8576f: one duplicate comment removed (9b55941); re-run on e53d02b: +40 -107, 10 comment lines, 0 copies
Security scan security-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 security clean on 9b55941 (job 4de47dd5) and e53d02b (job b2f55e81)
/security-review ran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK
/code-review medium 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
CI green on e53d02b: 10 pass, 3 skipped
Unresolved review threads 0

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.

Written for commit 2494d18. Summary will update on new commits.

View guided diff Turn on auto-fix

fetch_mcp_tools and call_mcp_tool each opened the transport, built a
ClientSession, initialized it under the same deadline and mapped
failures through _raise_mcp_failure. That now lives in one
_run_mcp_session helper, import guard included; each function keeps
only its own exchange.

The retry-once-with-the-looked-up-end-user logic was written three
times (per-account listing, search/execute listing, tool execution).
It is now retry_for_end_user, with the same rules: only a 400 naming an
account that was sent without an end user, and only if the lookup finds
one.

No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
@glebedel glebedel self-assigned this Nov 10, 2026
s2d2-s1 and others added 4 commits November 11, 2026 00:34
The retry condition is documented once, on retry_for_end_user, as the
toolset callers already rely on; the copy above the tool's call site
restated it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
retry_for_end_user already checks is_end_user_refusal before it calls the
look-up, and every caller goes through it, so the look-up's own check was a
second copy that could drift.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
Main changed the two MCP session bodies this branch folds into
_run_mcp_session. The shared helper stays, with main's edits carried over:
tools/list pages with list_tools(params=PaginatedRequestParams(...)), the
mcp imports drop their ty ignores, and the shared SSL context merged on its
own. The types import in fetch_mcp_tools sits inside _list, so it runs after
the helper's guarded import and a broken install still raises
ToolsetConfigError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
The pagination test only counted calls, so a regression to the old
positional cursor argument would still pass. Assert the first call sends
params=None and the second carries the next cursor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
@glebedel

Copy link
Copy Markdown
Contributor Author

Shipped as part of #274: that branch was built on this one, and its squash merge (7dfbf28) contains every change here. A second review pass on main found no regression (879 tests on mcp 2.3.0 and 1.30.0, validate.sh 6/6, and the end-user retry against the mock behaves exactly as before this change). The guidance follow-up is #275.

@glebedel glebedel closed this Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants