Use tools provided by external MCP servers directly in your Dify agents and workflow applications. Instead of being limited to existing Dify plugins, you can tap into a growing ecosystem of MCP servers that provide specialized capabilities.

This article shows how to use MCP tools within Dify. If you’re looking to publish an Dify application as an MCP server, check here.

Currently, only MCP servers supporting HTTP transport can be used.

​
Accessing MCP Server Management

Navigate to Tools → MCP in your Dify workspace. This is where you manage all external MCP servers that provide tools for your applications.

​
Adding an MCP Server

Click Add MCP Server (HTTP) to connect a new external tool provider:

Server URL: The HTTP endpoint of the MCP server (e.g., https://api.notion.com/mcp for a Notion integration).

Name & Icon: Give it a name that describes what tools it provides. Dify auto-fetches icons when ever it can from the server domain, or you can choose your own.

Server Identifier: A unique ID (lowercase, numbers, underscores, hyphens, max 24 characters) that Dify uses to track this server.

The server ID is permanent by design. If you change it, any existing agents or workflows using tools from this server will break. This is critical for application portability.

​
Authorization and Tool Discovery

After adding a server, Dify automatically:

  1. Discovers Available Tools: Checks what capabilities the server provides
  2. Handles Authorization: Initiates OAuth flows if the server requires authentication
  3. Fetches Tool Definitions: Downloads tool schemas so they can be used in your applications
  4. Updates Tool Inventory: Makes the tools available in agent and workflow builders

A server card is added once Dify successfully retrieves at least one usable tool:

​
Managing Connected Servers

Click any server card to:

Update Tools: Refresh available tools from the server. Use this when the external service adds new capabilities.

Re-authorize: Click on the authorization status to renew permissions.

Edit Configuration: Change server details.

Note: URL changes trigger re-authorization, server ID changes break existing applications.

Remove Server: Disconnects the server. Applications using its tools will show errors until you reconnect or remove those tools.

​
Using MCP Tools in Your Applications

Once a server is configured, its tools appear in the tool selection interface when building:

​
Agent Applications

  • MCP tools appear alongside built-in tools in the agent configuration
  • Tools are organized by server: “Notion MCP » Create Page”, “Linear MCP » Create Issue”
  • “Add All” option lets you quickly enable all tools from a server

​
Workflow Applications

  • MCP tools appear as available node types when building workflows
  • Each tool node shows which server it comes from (helpful for troubleshooting)
  • Complex tool parameters get JSON input interfaces for structured data

​
Agent Nodes in Workflows

  • MCP tools can be selected within agent nodes, just like in standalone agents

​
Customizing MCP Tools for Your Use Case

When you add an MCP tool to an agent node or agent, you can customize how it behaves:

​
Tool Description

You can override the default description that comes from the MCP server. This is useful for making the description more specific to your use case.

​
Parameter Configuration (Reasoning Config)

For each tool parameter, you can choose between:

Auto: Let the AI model determine the parameter value based on context (default behavior)

Fixed Value: Set a specific value (can be a static value or a variable) that will always be used, removing the parameter from AI inference

This is powerful for:

  • Setting consistent configuration values (like numResults: 10 for search tools)
  • Pre-filling parameters that shouldn’t change (like specific API endpoints or format preferences)
  • Simplifying tool usage by reducing the number of parameters the AI needs to handle

For example, with a web search tool, you might:

  • Keep query on “Auto” so the AI determines what to search for
  • Set numResults to a fixed value like “5” to limit response size
  • Set other parameters like search filters to fixed values for consistent behavior

​
Application Portability

When you export Dify applications that use MCP tools:

DSL Export: The exported DSL includes references to MCP servers by their IDs.

Environment Migration: To use the application elsewhere, add the same MCP servers with identical IDs in the target environment.

Sharing Applications: Document which MCP servers your application depends on, including URLs and required server IDs.

​
Troubleshooting Integration Issues

“Unconfigured Server”: Authorization failed or no tools found. Check server URL and re-authorize.

Missing Tools in Applications: Hit “Update Tools” - the external service may have changed its offerings.

Broken Applications After Server Changes: If you modified server IDs or removed servers, applications will show tool errors. Re-add servers with original IDs to restore functionality.

​
Best Practices

Consistent Server IDs: Use descriptive, permanent IDs like github-mcp or salesforce-api. Never change them once applications depend on them.

Environment Consistency: Keep the same MCP server configurations across development, staging, and production environments.

Tool Customization: Take advantage of parameter configuration to make tools behave consistently in your applications. Set fixed values for configuration parameters and let the AI handle dynamic inputs.

Tool Documentation: Document which external tools your applications use, what customizations you’ve made, and what they do. This helps team members understand application dependencies.

Gradual Updates: When external services update their MCP servers, test tool changes in development before updating production integrations.

Backup Plans: Consider how your applications will behave if an external MCP server becomes unavailable.

Edit this page | Report an issue