MCP Protocol Integration#

Dify supports the Model Context Protocol (MCP) in two directions:

• MCP client — Dify connects to remote MCP servers and invokes their tools from workflows or agents.
• MCP server (workflow-as-MCP) — any Dify app (Workflow, Chat, Advanced Chat, Agent Chat, Completion) can be exposed as an MCP server callable by external clients like Claude Desktop.

This article covers the server-side MCP implementation and the 2025-06-18 structured output upgrade introduced in PR #37892.

Key Source Files#

Protocol Version Negotiation#

Dify's MCP server supports three protocol versions 1:

initialize handshake — The client sends its preferred protocolVersion in the request body. The server echoes that version back if it is in the supported set; otherwise it falls back to SERVER_LATEST_PROTOCOL_VERSION (2025-06-18) 2.

Post-initialize requests — The client includes the MCP-Protocol-Version HTTP header. Resolution rules 2:

• Absent or empty → DEFAULT_NEGOTIATED_VERSION (2025-03-26)
• Known version → that version
• Unknown version → JSON-RPC INVALID_REQUEST (-32600), except for fire-and-forget notifications which always return HTTP 202
• initialize method → header is ignored; body version governs

The resolved version is threaded through the full call stack from the HTTP controller to each handler, with no global state 2.

Structured Output (2025-06-18)#

Structured output is gated by _supports_structured_output(), which uses lexical string comparison — valid because MCP versions are YYYY-MM-DD strings 3:

STRUCTURED_OUTPUT_MIN_VERSION = "2025-06-18"
_supports_structured_output(v) → v >= "2025-06-18"

tools/list — outputSchema and title#

When _supports_structured_output returns True, handle_list_tools() sets two extra fields on the Tool object 4:

• title — the app name (human-readable display name distinct from name)
• outputSchema — {"type": "object"} (permissive; declares the tool returns a JSON object)

For older clients these fields are None and are stripped via exclude_none serialization, preserving byte-for-byte backward compatibility 2.

tools/call — structuredContent#

handle_call_tool() calls extract_structured_output() to populate structuredContent when the protocol version qualifies. The content depends on app mode 5:

• WORKFLOW — returns the raw outputs mapping from the workflow execution (named output variables as keys)
• CHAT, ADVANCED_CHAT, AGENT_CHAT, COMPLETION — wraps the answer string as {"answer": <string>}

Both structuredContent and the legacy TextContent are always included for 2025-06-18 clients, per the MCP spec's backward-compatibility guidance 2.

MCP Client Side: Tool Entity Schema Population#

When Dify acts as an MCP client, MCPToolProviderController.from_entity() converts each remote MCP tool into a ToolEntity. The remote tool's outputSchema is stored directly in ToolEntity.output_schema 6:

output_schema=remote_mcp_tool.outputSchema or {}

ToolEntity.output_schema is defined in tool_entities.py as Mapping[str, object] defaulting to {}, with a validator that normalizes None to {} 7.

During invocation, MCPTool._invoke() processes result.structuredContent as follows 8:

• If both self.entity.output_schema and result.structuredContent are present, each key-value pair in structuredContent is yielded as a VariableMessage, making structured output fields available as named variables in the Dify workflow.
• If result.structuredContent is present but self.entity.output_schema is not defined, the entire structuredContent dictionary is yielded as a single JsonMessage.

Text content is always processed regardless, with JSON detection to yield JsonMessage or TextMessage appropriately 9.

MCP Client Transport#

The MCPClient supports two transports — SSE and Streamable-HTTP — with URL-path-based selection: paths ending in /mcp use Streamable-HTTP; paths ending in /sse use SSE. If the path is ambiguous, SSE is tried first and falls back to Streamable-HTTP on failure 10.

Backward Compatibility#

All 2025-06-18 fields (title, outputSchema, structuredContent) are optional in the Pydantic models and default to None. No database migrations or schema changes were needed — the upgrade was purely logic-layer 2. Clients that send protocolVersion: "2024-11-05" in the initialize handshake receive the identical pre-upgrade response shape.