** Please make sure you read the contribution guide and file the issues in the
right place. **
Contribution guide.
Is your feature request related to a problem? Please describe.
Yes. When an MCP session fails to initialize or crashes in the background due to transport errors (for example, an HTTP 403 Forbidden from the Agent Gateway / AGW), the true underlying error is often obscured or completely swallowed.
In the Python ADK (adk-python), this was caused by an AnyIO TaskGroup raising an ExceptionGroup which was formatted as a generic "unhandled errors in a TaskGroup (1 sub-exception)" message. In adk-js, we have similar asynchronous or nested error scenarios where background promises/exceptions might get swallowed or fail to propagate the actual root cause (such as HTTP response bodies or status codes) to the caller or the Agent. This results in generic or empty failures that make debugging and error recovery extremely difficult.
Describe the solution you'd like
We should bring feature parity with Python ADK's fix by implementing a robust error/exception formatter in adk-js within the MCP session context and transport layer.
Specifically, the library should:
- Recursively Extract Underlying Errors: If an aggregate or wrapped exception/promise rejection occurs during session initialization or background transport execution, recursively extract the leaf-level causes.
- Expose Transport Details: Capture and format specific transport details, including HTTP status messages and response bodies (e.g., the specific details of a
403 Forbidden or 401 Unauthorized response from AGW) when they are available.
- Propagate Cleanly: Surface this detailed, formatted message through the
ConnectionError (or equivalent JS/TS error class) so that it can be propagated all the way up to the user-facing Agent interface.
Describe alternatives you've considered
- Leaving errors as generic messages: This keeps the current behavior where the agent fails without providing any actionable context on what went wrong, which is a poor developer and user experience.
- Handling it strictly on the gateway side: While AGW correctly returns
403 status codes, the client-side library is ultimately responsible for capturing, unwrapping, and surfacing those error bodies rather than swallowing them.
Additional context
- This ensures feature parity with the Python ADK fix in
google/adk/tools/mcp_tool/session_context.py (released in adk v2.4.0).
- The goal is to ensure that IAP / Gateway authorization blocks or safety blocks are never returned as an empty response to the user.
** Please make sure you read the contribution guide and file the issues in the
right place. **
Contribution guide.
Is your feature request related to a problem? Please describe.
Yes. When an MCP session fails to initialize or crashes in the background due to transport errors (for example, an
HTTP 403 Forbiddenfrom the Agent Gateway / AGW), the true underlying error is often obscured or completely swallowed.In the Python ADK (
adk-python), this was caused by anAnyIO TaskGroupraising anExceptionGroupwhich was formatted as a generic"unhandled errors in a TaskGroup (1 sub-exception)"message. Inadk-js, we have similar asynchronous or nested error scenarios where background promises/exceptions might get swallowed or fail to propagate the actual root cause (such as HTTP response bodies or status codes) to the caller or the Agent. This results in generic or empty failures that make debugging and error recovery extremely difficult.Describe the solution you'd like
We should bring feature parity with Python ADK's fix by implementing a robust error/exception formatter in
adk-jswithin the MCP session context and transport layer.Specifically, the library should:
403 Forbiddenor401 Unauthorizedresponse from AGW) when they are available.ConnectionError(or equivalent JS/TS error class) so that it can be propagated all the way up to the user-facing Agent interface.Describe alternatives you've considered
403status codes, the client-side library is ultimately responsible for capturing, unwrapping, and surfacing those error bodies rather than swallowing them.Additional context
google/adk/tools/mcp_tool/session_context.py(released inadk v2.4.0).