MCP Client Transport and Connectivity#

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

Transport Selection and Fallback#

Protocol selection is performed in _initialize() using a two-step strategy:

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

   • Path ends in /mcp → streamablehttp_client
   • Path ends in /sse → sse_client

2. Automatic fallback. If the path segment doesn't match either key, Dify first attempts SSE; if that raises MCPConnectionError or ValueError, it falls back to Streamable-HTTP 3:

   ⧉

   try sse_client → except (MCPConnectionError, ValueError) → streamablehttp_client
   

   The ValueError catch was added in PR #29960 to handle transport initialization failures that surface before a connection-level error is raised. The earlier PR #22645 refactored the fallback from a broad try-except block into the explicit path-lookup + fallback structure now in place.

Once a transport is selected, connect_server() enters the transport context via ExitStack, then initializes a ClientSession and calls session.initialize().

Note on streamable-HTTP stream unpacking: The streamable client returns a 3-tuple (read_stream, write_stream, _); the SSE client returns a 2-tuple (read_stream, write_stream). connect_server() handles both cases 4.

Well-Known URL Discovery (RFC 9728)#

PR #29960 added RFC 9728–compliant OAuth protected resource metadata discovery. When validating or reconnecting to an MCP provider, Dify tries multiple well-known URLs in priority order:

1. URL from the WWW-Authenticate response header (if present)
2. /.well-known/oauth-protected-resource{path} (path insertion, for path-based multi-tenant deployments)
3. /.well-known/oauth-protected-resource (root fallback)

A parallel expansion was made for OAuth authorization server metadata to support both RFC 8414 and RFC 9728 variants (OIDC path-appending, OAuth 2.0 path insertion, and root endpoints).

Timeout Configuration#

Two timeout parameters are threaded through the entire stack from API request to HTTP transport (added in PR #23546):

These values are persisted per-provider in the MCPToolProvider database model (columns timeout FLOAT DEFAULT 30, sse_read_timeout FLOAT DEFAULT 300), configurable via the tool provider API endpoints.

The two transport implementations have different internal defaults when no explicit value is passed:

The streamablehttp_client also accepts timedelta objects, converting them to seconds internally.

Config flow:
API controller → MCPToolManageService → MCPToolProvider (DB) → MCPTool → MCPClient → transport

MCPClient.__init__ accepts timeout and sse_read_timeout directly 5 and passes them to the transport factory in connect_server() 6.

Header Forwarding#

MCPClient supports forwarding incoming request headers to the MCP server. Header values may contain {{ request.headers.<name> }} placeholders, which are substituted at construction time when a Flask request context is active 7.

Key Source Files#