MCP Client Transport and Connectivity#

MCPClient (api/core/mcp/mcp_client.py) is the single entry point for all outbound MCP server communication in Dify. It supports two transport backends — SSE (sse_client) and Streamable-HTTP (streamablehttp_client) — and manages their lifetimes via a contextlib.ExitStack 1.

Transport Selection and Fallback#

Protocol selection happens in _initialize(). The logic is a two-step heuristic:

1. URL-path detection. The last path segment of the server URL is matched against a connection_methods dict 2:

   • Ends in /mcp → streamablehttp_client
   • Ends in /sse → sse_client

2. Ambiguous-path fallback. If the segment matches neither key, the current code at cd61738f tries SSE first, falling back to Streamable-HTTP only on MCPConnectionError or ValueError 3.

⚠️ Known bug in the fallback order (as of this snapshot). The _initialize docstring says "fallback to SSE if streamable connection fails", meaning Streamable-HTTP should be the default. The actual else branch does the opposite — tries SSE first — and the fallback exception handling was too narrow before PR #42177. httpx transport errors (ConnectError, ReadTimeout, RemoteProtocolError, etc.) leaked out of sse_client unchanged, preventing fallback to Streamable-HTTP and surfacing as opaque 500 responses 4.

Three fixes have been proposed/merged:

After these fixes, the corrected fallback order for ambiguous URLs is:

streamablehttp_client → (on transport error) → sse_client
                      → (on MCPAuthError) → re-raise immediately

Stream unpacking: streamablehttp_client returns a 3-tuple (read_stream, write_stream, _); sse_client returns a 2-tuple. connect_server() handles both cases 7.

Timeout Configuration#

Two timeout parameters are accepted by MCPClient.__init__ and forwarded to the transport factory in connect_server():

Both are persisted per-provider in the MCPToolProvider database model (api/models/tools.py) and surfaced via the tool-provider API. Improved timeout handling was introduced in PR #23546 8.

The full config flow is:

API controller → MCPToolManageService → MCPToolProvider (DB) → MCPTool → MCPClient → transport

Header Forwarding#

MCPClient supports dynamic header values. At construction time, any header value matching {{ request.headers.<name> }} is resolved against the active Flask request context 9. This enables per-request credential forwarding to MCP servers that require upstream authentication headers.

Error Handling and Exception Translation#

sse_client wraps low-level transport failures in MCPConnectionError to maintain a consistent error contract across the stack. PR #42177 introduced a catch block for httpx.RequestError (which includes ConnectError, ConnectTimeout, ReadTimeout, WriteTimeout, PoolTimeout, RemoteProtocolError, and other transport-layer failures). Without this translation:

• The MCPClient._initialize() fallback logic fails because it only catches MCPConnectionError and ValueError
• The console MCP endpoints (ToolMCPAuthApi, etc.) cannot map the error to a 4xx response with a readable message, so users see {"message":"Internal Server Error","code":"unknown","status":500} instead of the actual connection failure reason

The catch block in sse_client.py re-raises transport errors as:

raise MCPConnectionError(f"Failed to connect to SSE endpoint: {exc}") from exc

This preserves the original error message (connection refused, timeout, DNS failure, etc.) while allowing callers to handle it uniformly. A similar fix in auth_flow.py wraps HTTPStatusError from failed dynamic client registration in ValueError so the auth endpoint can return a proper 400 response instead of a 500.

Key Source Files#

Related Issues and PRs#

• Issue #39301 — httpx.ReadTimeout not caught; SSE-first fallback blocks authorization for 300 s 4
• Issue #40001 — httpx.RemoteProtocolError escaping as 500 during MCP auth
• PR #42177 — Wrap httpx.RequestError in MCPConnectionError within sse_client; wrap HTTPStatusError in ValueError in auth_flow.py
• PR #40111 — Canonical fix: prefer streamable-http, catch httpx.TransportError 6
• PR #39344 — Earlier community fix, same intent, closed in favour of #40111 5
• PR #29960 — Added ValueError to the caught exceptions (RFC 9728 discovery) 12
• PR #23546 — Improved timeout handling 8
• PR #22645 — Introduced path-lookup + fallback structure 13