fix(mcp): fail fast on non-MCP HTTP content type instead of waiting 60s

[uzunkuyruk]

What does this PR do?

Fixes a 60-second startup hang when a misconfigured HTTP MCP server URL returns text/html instead of a valid MCP response.

Before: The SDK logged the content type error immediately, but Hermes waited the full _DEFAULT_CONNECT_TIMEOUT (60s) before surfacing a CancelledError with no actionable context. With 3 retries + backoff, a single bad URL could block startup for the full timeout.

After: Fails in <1s with a clear, actionable message.

Three-part fix:

• _MCPInvalidContentTypeError — new non-retryable exception class for non-MCP content type responses
• _detect_non_mcp_content_type — httpx response event hook that raises immediately when a 2xx response has a non-MCP content type (application/json or text/event-stream are the only valid types), cancelling the transport before the timeout expires
• Non-retryable guard — treats _MCPInvalidContentTypeError like an auth error, skipping the 3x retry + backoff loop entirely

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

References

Fixes #36052

Checklist

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• My PR contains only changes related to this fix

[alt-glitch]

Competing fix with #36058 — both address #36052 (MCP HTML content-type blocking discovery for 60s). This PR uses an httpx event hook approach; #36058 uses a HEAD preflight probe and includes tests. Maintainer should pick one approach.

[mxnstrexgl]

LGTM — automated review passed. No security, quality, or test coverage issues detected.

[uzunkuyruk]

Added test coverage in the latest commit:

• _MCPInvalidContentTypeError instantiation and message format
• text/html on 200 raises the error
• Valid MCP content types (application/json, text/event-stream) pass through
• 4xx/5xx responses are exempt from content-type checking

[liuhao1024]

The test file has class TestMCPInvalidContentTypeError defined twice (line 11 and line 98 of the diff), with identical method names. In Python, the second class definition shadows the first — the first class's 5 test methods become dead code.

Since both classes have the same 5 methods (test_invalid_content_type_error_is_non_retryable, test_invalid_content_type_error_message_is_actionable, test_html_response_raises_invalid_content_type_error, test_valid_mcp_content_types_do_not_raise, test_4xx_responses_do_not_raise_content_type_error), pytest still collects and runs 5 tests from the second class. So the coverage is there, but the first class is wasted code.

Fix: remove the first class definition (lines 11–95 of the new file) and keep only the second.

Additionally, the async tests (test_html_response_raises_invalid_content_type_error, test_valid_mcp_content_types_do_not_raise, test_4xx_responses_do_not_raise_content_type_error) use a simulate_hook helper that duplicates the production hook logic inline rather than testing the actual _detect_non_mcp_content_type hook. This means the tests validate the simulation, not the real code — if the production hook's logic diverges from the simulation, the tests still pass. Consider testing the actual hook via the httpx client's event_hooks mechanism instead.

[dsameer0-code]

Unsubscribe

…

On Mon, Jun 1, 2026 at 7:32 AM liuhao1024 ***@***.***> wrote: *liuhao1024* left a comment (NousResearch/hermes-agent#36064) <#36064 (comment)> The test file has class TestMCPInvalidContentTypeError defined *twice* (line 11 and line 98 of the diff), with identical method names. In Python, the second class definition shadows the first — the first class's 5 test methods become dead code. Since both classes have the same 5 methods ( test_invalid_content_type_error_is_non_retryable, test_invalid_content_type_error_message_is_actionable, test_html_response_raises_invalid_content_type_error, test_valid_mcp_content_types_do_not_raise, test_4xx_responses_do_not_raise_content_type_error), pytest still collects and runs 5 tests from the second class. So the coverage is there, but the first class is wasted code. *Fix*: remove the first class definition (lines 11–95 of the new file) and keep only the second. Additionally, the async tests ( test_html_response_raises_invalid_content_type_error, test_valid_mcp_content_types_do_not_raise, test_4xx_responses_do_not_raise_content_type_error) use a simulate_hook helper that duplicates the production hook logic inline rather than testing the actual _detect_non_mcp_content_type hook. This means the tests validate the simulation, not the real code — if the production hook's logic diverges from the simulation, the tests still pass. Consider testing the actual hook via the httpx client's event_hooks mechanism instead. — Reply to this email directly, view it on GitHub <#36064?email_source=notifications&email_token=BVAK7EIEH6X7IB3ISY7FS4L45VSVFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINJZGIYTINZSGI42M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4592147229>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BVAK7EOCOLCBXYW3UDA4FJT45VSVFAVCNFSM6AAAAACZUWDWQ2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKOJSGE2DOMRSHE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BVAK7EPPP2IRQLIDHZLM34345VSVFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINJZGIYTINZSGI42M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android <https://github.com/notifications/mobile/android/BVAK7EO44FBSO7NSARMFLH345VSVFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINJZGIYTINZSGI42M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[uzunkuyruk]

Second point also addressed in the latest commit replaced all three simulate_hook async tests with real httpx.AsyncBaseTransport mocks that fire the hook via the actual event_hooks={'response': [...]} mechanism, matching exactly how production code registers _detect_non_mcp_content_type.

[teknium1]

Merged via #37133 (#37133) — same root cause as your PR, you and @liuhao1024 diagnosed it independently within ~30 min of each other.

Heads-up on the in-SDK event-hook approach for future reference: the hook raises inside the MCP SDK's anyio task group, so the error reaches the retry loop wrapped in an ExceptionGroup rather than as a bare _MCPInvalidContentTypeError — the isinstance guard never matched, so it still burned all 3 retries (verified live against mcp 1.26.0). The shipped fix uses a preflight probe outside the task group, which avoids the wrapping entirely. You're credited as a co-author on the merged commit. Thanks for the report and the work!