feat(api): add MCP user-identity forwarding (#36839)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

api/core/tools/entities/api_entities.py

@@ -54,6 +54,9 @@ class ToolProviderApiEntity(BaseModel):
     configuration: MCPConfiguration | None = Field(
         default=None, description="The timeout and sse_read_timeout of the MCP tool"
     )
+    # M3 — user-identity forwarding selector. Round-tripped through the
+    # console API so the create/edit modal can hydrate the toggle state.
+    identity_mode: str = Field(default="off", description="Identity-forwarding mechanism: 'off' or 'idp_token'")
     # Workflow
     workflow_app_id: str | None = Field(default=None, description="The app id of the workflow tool")
 
@@ -92,6 +95,9 @@ class ToolProviderApiEntity(BaseModel):
                 optional_fields.update(self.optional_field("is_dynamic_registration", self.is_dynamic_registration))
                 optional_fields.update(self.optional_field("masked_headers", self.masked_headers))
                 optional_fields.update(self.optional_field("original_headers", self.original_headers))
+                # M3 — forwarding selector. Always emit ("off" is a valid
+                # value that the UI must hydrate, not skip).
+                optional_fields["identity_mode"] = self.identity_mode
             case ToolProviderType.WORKFLOW:
                 optional_fields.update(self.optional_field("workflow_app_id", self.workflow_app_id))
             case _:

api/core/tools/mcp_tool/provider.py

@@ -1,6 +1,6 @@
 from typing import Any, Self
 
-from core.entities.mcp_provider import MCPProviderEntity
+from core.entities.mcp_provider import IdentityMode, MCPProviderEntity
 from core.mcp.types import Tool as RemoteMCPTool
 from core.tools.__base.tool_provider import ToolProviderController
 from core.tools.__base.tool_runtime import ToolRuntime
@@ -28,6 +28,7 @@ class MCPToolProviderController(ToolProviderController):
         headers: dict[str, str] | None = None,
         timeout: float | None = None,
         sse_read_timeout: float | None = None,
+        identity_mode: IdentityMode = IdentityMode.OFF,
     ):
         super().__init__(entity)
         self.entity: ToolProviderEntityWithPlugin = entity
@@ -37,6 +38,7 @@ class MCPToolProviderController(ToolProviderController):
         self.headers = headers or {}
         self.timeout = timeout
         self.sse_read_timeout = sse_read_timeout
+        self.identity_mode: IdentityMode = identity_mode
 
     @property
     def provider_type(self) -> ToolProviderType:
@@ -105,6 +107,7 @@ class MCPToolProviderController(ToolProviderController):
             headers=entity.headers,
             timeout=entity.timeout,
             sse_read_timeout=entity.sse_read_timeout,
+            identity_mode=entity.identity_mode,
         )
 
     def _validate_credentials(self, user_id: str, credentials: dict[str, Any]):
@@ -134,6 +137,7 @@ class MCPToolProviderController(ToolProviderController):
             headers=self.headers,
             timeout=self.timeout,
             sse_read_timeout=self.sse_read_timeout,
+            identity_mode=self.identity_mode,
         )
 
     def get_tools(self) -> list[MCPTool]:
@@ -151,6 +155,7 @@ class MCPToolProviderController(ToolProviderController):
                 headers=self.headers,
                 timeout=self.timeout,
                 sse_read_timeout=self.sse_read_timeout,
+                identity_mode=self.identity_mode,
             )
             for tool_entity in self.entity.tools
         ]

api/core/tools/mcp_tool/tool.py

@@ -6,6 +6,8 @@ import logging
 from collections.abc import Generator, Mapping
 from typing import Any, cast
 
+from configs import dify_config
+from core.entities.mcp_provider import IdentityMode
 from core.mcp.auth_client import MCPClientWithAuthRetry
 from core.mcp.error import MCPConnectionError
 from core.mcp.types import (
@@ -25,6 +27,11 @@ from graphon.model_runtime.entities.llm_entities import LLMUsage, LLMUsageMetada
 
 logger = logging.getLogger(__name__)
 
+# Custom header used to carry the forwarded SSO access token. Picked to avoid
+# stomping on the workspace-scoped Authorization header (provider OAuth /
+# user-supplied custom credentials), which would silently break those flows.
+FORWARDED_IDENTITY_HEADER = "X-Dify-SSO-Access-Token"
+
 
 class MCPTool(Tool):
     def __init__(
@@ -38,6 +45,7 @@ class MCPTool(Tool):
         headers: dict[str, str] | None = None,
         timeout: float | None = None,
         sse_read_timeout: float | None = None,
+        identity_mode: IdentityMode = IdentityMode.OFF,
     ):
         super().__init__(entity, runtime)
         self.tenant_id = tenant_id
@@ -47,6 +55,7 @@ class MCPTool(Tool):
         self.headers = headers or {}
         self.timeout = timeout
         self.sse_read_timeout = sse_read_timeout
+        self.identity_mode: IdentityMode = identity_mode
         self._latest_usage = LLMUsage.empty_usage()
 
     def tool_provider_type(self) -> ToolProviderType:
@@ -60,7 +69,7 @@ class MCPTool(Tool):
         app_id: str | None = None,
         message_id: str | None = None,
     ) -> Generator[ToolInvokeMessage, None, None]:
-        result = self.invoke_remote_mcp_tool(tool_parameters)
+        result = self.invoke_remote_mcp_tool(tool_parameters, user_id=user_id, app_id=app_id)
 
         # Extract usage metadata from MCP protocol's _meta field
         self._latest_usage = self._derive_usage_from_result(result)
@@ -234,6 +243,7 @@ class MCPTool(Tool):
             headers=self.headers,
             timeout=self.timeout,
             sse_read_timeout=self.sse_read_timeout,
+            identity_mode=self.identity_mode,
         )
 
     def _handle_none_parameter(self, parameter: dict[str, Any]) -> dict[str, Any]:
@@ -246,7 +256,26 @@ class MCPTool(Tool):
             if value is not None and not (isinstance(value, str) and value.strip() == "")
         }
 
-    def invoke_remote_mcp_tool(self, tool_parameters: dict[str, Any]) -> CallToolResult:
+    @property
+    def _forwarding_requested(self) -> bool:
+        """True only when the configured identity_mode wants forwarding AND
+        the deployment actually has the enterprise side that can mint tokens.
+        Non-enterprise installs treat the DB value as a no-op — a stale row
+        won't trigger a 5xx against a missing inner-API endpoint."""
+        return self.identity_mode != IdentityMode.OFF and dify_config.ENTERPRISE_ENABLED
+
+    def invoke_remote_mcp_tool(
+        self,
+        tool_parameters: dict[str, Any],
+        user_id: str | None = None,
+        app_id: str | None = None,
+    ) -> CallToolResult:
+        # Fail closed: forwarding requires user_id (refuse before any DB I/O).
+        if self._forwarding_requested and not user_id:
+            raise ToolInvokeError(
+                "Forward-user-identity is enabled for this MCP provider but no end-user context was supplied."
+            )
+
         headers = self.headers.copy() if self.headers else {}
         tool_parameters = self._handle_none_parameter(tool_parameters)
 
@@ -271,6 +300,15 @@ class MCPTool(Tool):
                 if tokens and tokens.access_token:
                     headers["Authorization"] = f"{tokens.token_type.capitalize()} {tokens.access_token}"
 
+        # Forwarded identity rides in a custom header so workspace-scoped
+        # provider credentials (Authorization / custom Headers) keep working
+        # untouched. The MCP server is expected to read X-Dify-SSO-Access-Token
+        # when identity forwarding is configured.
+        forward_identity_active = False
+        if self._forwarding_requested and user_id:
+            self._inject_forwarded_identity(headers, user_id=user_id, app_id=app_id, audience=server_url)
+            forward_identity_active = True
+
         # Step 2: Session is now closed, perform network operations without holding database connection
         # MCPClientWithAuthRetry will create a new session lazily only if auth retry is needed
         try:
@@ -280,9 +318,44 @@ class MCPTool(Tool):
                 timeout=self.timeout,
                 sse_read_timeout=self.sse_read_timeout,
                 provider_entity=provider_entity,
+                forward_identity_active=forward_identity_active,
             ) as mcp_client:
                 return mcp_client.invoke_tool(tool_name=self.entity.identity.name, tool_args=tool_parameters)
         except MCPConnectionError as e:
             raise ToolInvokeError(f"Failed to connect to MCP server: {e}") from e
         except Exception as e:
             raise ToolInvokeError(f"Failed to invoke tool: {e}") from e
+
+    def _inject_forwarded_identity(
+        self,
+        headers: dict[str, str],
+        *,
+        user_id: str,
+        app_id: str | None,
+        audience: str,
+    ) -> None:
+        """Call the enterprise IssueMCPToken endpoint and stamp the issued
+        token into X-Dify-SSO-Access-Token.
+
+        A custom header is used (rather than Authorization) so it composes
+        with workspace-scoped provider credentials — the user may have OAuth
+        tokens or a custom Authorization header configured on the MCP
+        provider, and forwarding must not silently overwrite them.
+
+        Errors are surfaced as ToolInvokeError so the workflow halts with a
+        clear message instead of silently dropping identity and hitting the
+        MCP server unauthenticated.
+        """
+        from services.enterprise.base import MCPTokenError
+        from services.enterprise.enterprise_service import EnterpriseService
+
+        try:
+            token, _expires_at = EnterpriseService.issue_mcp_token(
+                user_id=user_id,
+                tenant_id=self.tenant_id,
+                app_id=app_id,
+                audience=audience,
+            )
+        except MCPTokenError as e:
+            raise ToolInvokeError(f"Failed to obtain forwarded identity token: {e}") from e
+        headers[FORWARDED_IDENTITY_HEADER] = token