feat(mcp): add support for MCP elicitation -32042 error handling

[Christian-kam]

Description

When an MCP server like AgentCore Gateway returns a -32042 (URLElicitationRequiredError) on tools/call, the
MCP Python SDK raises McpError. The current MCPClient._handle_tool_execution_error
catches it and returns a generic error string, losing the authorization URL(s) embedded in
error.data.elicitations. This breaks OAuth consent flows that rely on URL mode elicitation
(e.g., AgentCore Gateway 3LO, or any MCP server using the 2025-11-25 spec).

This PR modifies _handle_tool_execution_error to detect McpError with code -32042,
parse the error data using the MCP SDK's ElicitationRequiredErrorData model, and include
the authorization URL(s) in the tool result text with a URL_ELICITATION_REQUIRED prefix.
The LLM can then present the URL to the user and retry the tool call after consent completes.

Changes

File: strands/tools/mcp/mcp_client.py

• Added imports: McpError from mcp.shared.exceptions, ElicitationRequiredErrorData from mcp.types
• Modified MCPClient._handle_tool_execution_error: added a check at the top of the method for -32042 errors, parses ElicitationRequiredErrorData, extracts URL(s) and message(s), and returns them in the tool result. Falls through to original behavior for all non-32042 errors.

How the two elicitation paths work together

The MCP 2025-11-25 spec defines two ways a server can request user authorization:

Path	Mechanism	Handled by
Server-initiated	Server sends elicitation/create request to client	elicitation_callback on MCPClient (existing, unchanged)
Error-based	Server returns -32042 error on tools/call	_handle_tool_execution_error (this PR)

Both paths can coexist. The elicitation_callback handles case 1 via the MCP Python SDK's
ClientSession. This PR handles case 2, where the error is raised as McpError and caught
by call_tool_async/call_tool_sync.

Related Issues

Closes #1742

Specifically addresses the "URL Mode Elicitation" item under Major Changes in the MCP 2025-11-25 spec:

• URL Mode Elicitation
• URLElicitationRequiredError (code -32042)
• MCP 2025-11-25 Changelog

Documentation PR

N/A

Type of Change

New feature

Testing

Unit tests

Test case	Input	Expected output
-32042 with valid ElicitationRequiredErrorData	McpError(ErrorData(code=-32042, data={"elicitations": [{"mode": "url", "url": "https://...", "message": "Please authorize"}]}))	MCPToolResult with URL_ELICITATION_REQUIRED and the URL
-32042 with multiple URLs	Same as above with 2+ elicitations	All URLs included, newline-separated
-32042 with malformed data	McpError(ErrorData(code=-32042, data="invalid"))	Falls through to "Tool execution failed: ..."
-32042 with no URLs in elicitations	McpError(ErrorData(code=-32042, data={"elicitations": [{"mode": "url"}]}))	Falls through to "Tool execution failed: ..."
Different McpError code	McpError(ErrorData(code=-32600, ...))	Falls through to "Tool execution failed: ..." (no change)
Non-McpError exception	RuntimeError("connection lost")	Falls through to "Tool execution failed: ..." (no change)

Integration test

Tested with AgentCore Gateway using LinkedIn as a 3LO OAuth target:

1. Agent calls LinkedInAuthCode___getUserInfo
2. Gateway returns -32042 with authorization URL
3. LLM receives the URL in the tool result and presents it to the user
4. User completes OAuth consent in browser
5. Agent retries the tool call — succeeds and returns LinkedIn user data

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Christian-kam]

@yonib05 Could you review my PR? It addresses the URLElicitationRequiredError (code -32042) point raised in your issue See #1659.