---
title: "Using MCP Tools"
---

Use [tools](https://modelcontextprotocol.io/docs/concepts/tools) provided by external [MCP](https://modelcontextprotocol.io/introduction) servers directly in your Dify agents and workflow applications. Instead of being limited to existing Dify plugins, you can tap into a growing [ecosystem](https://mcpservers.org/) of MCP servers that provide specialized capabilities.

<Note>
  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](/en/guides/application-publishing/publish-mcp).
</Note>

<Info>
  Currently, only MCP servers supporting [HTTP transport](https://modelcontextprotocol.io/docs/concepts/architecture#transport-layer) can be used.
</Info>

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

![6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png](/images/6cef1436fcc13a65ccedb54bcf5ab77eb87b8faba1098a85951839fb1907f2d2.png)

## Adding an MCP Server

<img
  src="/images/b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
  alt="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
  title="b5429131836c1caae84f4ce8b3b806221e39636723644961ce2f2a97d5421f16.png"
  className="mr-auto"
  style={{ width:"70%" }}
/>

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.

<Warning>
  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](##application-portability).
</Warning>

## 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:

![fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png](/images/fcef5ecad1deca82a1d8988c4bcb7cec745a0cd47945ff05fca588502cfaafbc.png)

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

<img
  src="/images/7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
  alt="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
  title="7b526a64ff34b10a357511b2cd3e42f251a6786210eac71c58ca7bfccdf63f0c.png"
  className="mx-auto"
  style={{ width:"59%" }}
/>

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

**Edit Configuration**: Change server details.

<Warning>
  Note: URL changes trigger re-authorization, server ID changes break existing applications.
</Warning>

<img
  src="/images/CleanShot2025-07-07at07.28.04@2x.png"
  alt="CleanShot 2025-07-07 at 07.28.04@2x.png"
  title="CleanShot 2025-07-07 at 07.28.04@2x.png"
  className="mx-auto"
  style={{ width:"60%" }}
/>

**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:

<img
  src="/images/CleanShot2025-07-07at07.41.33@2x.png"
  alt="CleanShot 2025-07-07 at 07.41.33@2x.png"
  title="CleanShot 2025-07-07 at 07.41.33@2x.png"
  className="mx-auto"
  style={{ width:"57%" }}
/>

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

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/guides/tools/mcp.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

