Using MCP Tools

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.

​

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.

​

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. 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