MCP Provider Architecture#

The MCP provider stack uses a three-layer pattern to separate persistence, domain logic, and presentation:

MCPToolProvider (SQLAlchemy)
    ↓ .to_entity()
MCPProviderEntity (Pydantic)
    ↓ MCPToolProviderController.from_entity()
MCPToolProviderController

Layer 1 — MCPToolProvider (Persistence)#

MCPToolProvider is the SQLAlchemy model backing the tool_mcp_providers table. It stores:

• server_url — encrypted URL, with a separate server_url_hash for uniqueness enforcement 1
• encrypted_credentials and encrypted_headers — JSON-encoded blobs of encrypted values 2
• authed — boolean flag indicating whether OAuth is complete 3
• tools — JSON-serialized list of MCP tool definitions fetched from the remote server 4
• timeout / sse_read_timeout — connection timeouts (defaults: 30s / 300s) 5
• identity_mode — controls end-user identity forwarding ("off" or "idp_token") 6

The .credentials, .headers, and .tool_dict properties deserialize the raw JSON columns 7. The .to_entity() method delegates to MCPProviderEntity.from_db_model() 8.

Layer 2 — MCPProviderEntity (Domain)#

MCPProviderEntity is a Pydantic BaseModel that adds business logic on top of the raw database columns. It is the authoritative object passed around the service layer. Key responsibilities:

Decryption helpers — decrypt_server_url(), decrypt_headers(), and decrypt_credentials() all delegate to _decrypt_dict(), which dynamically builds an encrypter config for only the string fields, skipping nested dicts (e.g., client_information) that are not themselves encrypted.

Credential masking — The _mask_value() helper exposes only the first 2 and last 2 characters of long secrets (using "*" for the rest); values shorter than 6 characters are fully masked 9. Three public methods apply this:

• masked_server_url() — strips the URL path to /******
• masked_headers() — masks every header value
• masked_credentials() — masks client_id and client_secret from nested OAuth client_information

API serialization — to_api_response() produces the JSON object returned by the REST API. It accepts an include_sensitive flag: when False (used for list views), expensive decryption is skipped and masked_headers is returned as {} 10.

OAuth helpers — retrieve_tokens() returns OAuthTokens if the provider is authed (returns None on empty access_token to avoid sending an invalid Authorization header). retrieve_client_information() reconstructs an OAuthClientInformation from nested credentials, decrypting encrypted_client_secret inline. client_metadata builds OAuthClientMetadata for dynamic registration, selecting authorization_code vs client_credentials grant type from the stored client_information. decrypt_authentication() assembles the final headers dict to send to the MCP server — using explicit headers if present, otherwise injecting a Bearer token from retrieve_tokens().

IdentityMode enum — IdentityMode has two values: OFF (no forwarding, default) and IDP_TOKEN (forward an SSO access token from dify-enterprise). This is stored in MCPToolProvider.identity_mode and surfaced through the entity.

Layer 3 — MCPToolProviderController (Presentation)#

MCPToolProviderController wraps an MCPProviderEntity (or DB model) into a ToolProviderController, making the MCP provider consumable by the same tool invocation pipeline used by built-in and API tools.

• from_db() — convenience classmethod that calls db_provider.to_entity() then from_entity()
• from_entity() — converts each raw tool dict in MCPProviderEntity.tools to a ToolEntity using ToolTransformService.convert_mcp_schema_to_parameter(), wraps them in a ToolProviderEntityWithPlugin, and returns a fully initialized controller
• get_tool() / get_tools() 11 — instantiate MCPTool objects on demand

Author fields at both tool and provider level are intentionally set to "Anonymous" because per-tool authorship is not persisted 12.

Service Layer Entry Point#

MCPToolManageService is the primary service that orchestrates CRUD operations on MCP providers. It queries MCPToolProvider rows, calls .to_entity() to get MCPProviderEntity objects, and uses MCPToolProviderController.from_db() when a controller is needed for tool invocation or credential management 13.

Key Source Files#