Last verified: April 2026 MCP Integration New in 2026

Dify + MCP Guide 2026: Connect AI Agents to Any Tool

Model Context Protocol (MCP) is the new universal standard for connecting AI models to external tools. This guide shows you how to wire MCP servers into Dify — giving your agents access to your filesystem, GitHub, Slack, databases, and any API, all through one standardized interface.

Host Dify on Hetzner → 1-Click Deploy on Elestio

What is MCP (Model Context Protocol)?

Model Context Protocol (MCP) is an open standard introduced by Anthropic in late 2024. It defines a universal way for AI language models to connect to external tools and data sources. Before MCP, every AI platform needed its own custom integration for every tool — a GitHub integration, a database connector, a file reader, each built from scratch. MCP changes that entirely.

The best analogy: MCP is like USB-C for AI. Just as USB-C lets you plug any device into any computer, MCP lets any AI agent connect to any MCP-compatible tool server. One standard, infinite extensibility.

Technical note: MCP uses a client-server architecture over HTTP or stdio. The AI (client) sends requests to MCP servers, which expose "tools" — functions the AI can call. The server returns structured results. The protocol is language-agnostic: servers can be written in Node.js, Python, Go, or any language.

Standardized

One protocol for all tools. Build once, connect anywhere.

Open Source

Apache 2.0 licensed. Community-driven ecosystem of servers.

Secure

Servers run locally or on your private network. Your data stays yours.

Extensible

Build custom MCP servers for any API, database, or service.

Dify as an MCP Client

Dify supports MCP natively as an MCP client, meaning your Dify agents can communicate with any MCP server out of the box. When you add an MCP server to Dify, it automatically discovers all the tools that server exposes, and makes them available inside your Agent apps. Your AI can then decide when to call those tools — just like it would with any other function.

This is a significant upgrade over traditional API integrations. Instead of manually defining every API call as a Dify "custom tool", you point Dify at an MCP server and it reads the entire tool catalog automatically. Add a GitHub MCP server and your agent instantly gains the ability to list repos, read files, create issues, and review pull requests.

What you can connect via MCP

📁

Local Filesystem

Read and write files on your server. Perfect for document processing.

🐙

GitHub

Repos, branches, PRs, issues, code search, commit history.

💬

Slack

Read and send messages, list channels, search conversation history.

🐘

PostgreSQL

Run read-only SQL queries, explore schemas, analyze data.

🔍

Web Search

Real-time web search via Brave Search or DuckDuckGo APIs.

🌐

Puppeteer

Browser automation — navigate pages, extract content, take screenshots.

How to Connect an MCP Server to Dify

Adding an MCP server as a tool in Dify takes about 2 minutes. Here's the complete step-by-step process:

Start your MCP server

Launch your MCP server locally or on your server. For example, to start the official Anthropic filesystem server: run npx @modelcontextprotocol/server-filesystem /path/to/your/files — this starts an HTTP MCP server on port 3000 by default.

Open Dify Tools

In your Dify instance, go to the top navigation and click Tools. Then click Custom Tools in the left sidebar.

Create a new MCP tool

Click the "+ Create" button. In the tool type selector, choose MCP Server (not OpenAPI).

Enter the MCP server URL

Paste your MCP server URL, for example http://localhost:3000/mcp or http://your-server-ip:3000/mcp. If your server requires authentication, enter the auth token in the Authorization header field.

Auto-discovery

Dify fetches the server's tool manifest automatically. You'll see a list of all tools the server exposes — e.g., "read_file", "list_directory", "write_file" for a filesystem server.

Add to Agent app

Open or create an Agent app in Dify. In the Tools section, click Add Tool and select your MCP server. Your agent can now use all the discovered tools in its reasoning loop.

Self-hosted tip: If Dify and your MCP server run on the same host, use the server's internal IP or hostname, not localhost — since Dify runs inside Docker. For example: http://172.17.0.1:3000/mcp or http://host.docker.internal:3000/mcp on macOS/Windows.

Popular MCP Servers for Dify

Anthropic and the community maintain a growing ecosystem of MCP servers. These are the most useful ones to connect to Dify:

MCP Server	What it does	Key tools	Install
filesystem	Read and write local files	read_file, write_file, list_directory, search_files	npx @modelcontextprotocol/server-filesystem
github	GitHub repos, PRs, issues	get_file_contents, create_issue, list_pull_requests, search_code	npx @modelcontextprotocol/server-github
slack	Slack messages & channels	list_channels, get_messages, send_message, search_messages	npx @modelcontextprotocol/server-slack
postgresql	Read-only SQL database access	query, list_tables, describe_table	npx @modelcontextprotocol/server-postgres
brave-search	Real-time web search	brave_web_search, brave_local_search	npx @modelcontextprotocol/server-brave-search
puppeteer	Browser automation & scraping	navigate, screenshot, get_content, click, fill	npx @modelcontextprotocol/server-puppeteer
everything	Windows file indexing search	search, get_file_info	npx @modelcontextprotocol/server-everything

All official servers are maintained at github.com/modelcontextprotocol/servers. The community also maintains hundreds of third-party MCP servers for tools like Notion, Linear, Jira, Stripe, and more.

Setting Up an MCP Server: Step-by-Step Example

Let's walk through a complete example: setting up the Anthropic filesystem MCP server so your Dify agent can read and write files on your server.

Step 1: Install Node.js 18+ (skip if already installed)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

Step 2: Start the filesystem MCP server

npx @modelcontextprotocol/server-filesystem /home/user/documents

# Server starts on http://localhost:3000/mcp

Step 3: Run as a background service (optional)

npm install -g pm2
pm2 start "npx @modelcontextprotocol/server-filesystem /home/user/documents" --name mcp-filesystem
pm2 save && pm2 startup

Step 4: Test the server

curl http://localhost:3000/mcp
# Should return: {"name":"filesystem","version":"...","tools":[...]}

Step 5: GitHub MCP server (with authentication)

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
  npx @modelcontextprotocol/server-github

# Create a GitHub PAT at: github.com/settings/tokens

Real-World Use Cases

Here are three production-ready Dify + MCP setups you can replicate today:

📄

Use Case 1: AI Document Assistant

Connect the filesystem MCP server to a Dify Agent. Your AI can now browse your document folders, read contracts, extract key data, compare versions, and write summaries back to disk — all through natural language. Ask "summarize all PDF reports in /reports/Q1 and create an executive summary" and watch it work.

MCP Server: filesystem Dify App: Agent Model: Claude 3.5 Sonnet or GPT-4o

🐙

Use Case 2: GitHub PR Reviewer

Connect the GitHub MCP server to Dify. Build an Agent that automatically reviews pull requests: it lists open PRs, reads the diff, checks coding standards, identifies potential bugs, and posts a review comment — all without leaving Dify's interface. Run it on a schedule via Dify workflows for hands-off code review.

MCP Server: github Dify App: Workflow + Agent Needs: GitHub PAT token

🐘

Use Case 3: Database Analyst

Connect the PostgreSQL MCP server to Dify with read-only credentials. Build a natural language data analyst: users ask business questions in plain English, the agent writes SQL queries, executes them against your database, and returns insights in human-readable form. No SQL knowledge needed by end users.

MCP Server: postgresql Dify App: Chatbot Security: read-only DB user

Frequently Asked Questions

What is MCP (Model Context Protocol)?

MCP (Model Context Protocol) is an open standard by Anthropic that defines how AI models connect to external tools and data sources. Think of it as 'USB-C for AI' — instead of custom integrations for every tool, one standard works everywhere. Dify supports MCP as a client, letting your agents use any MCP server.

What can I connect to Dify via MCP?

Via MCP you can connect Dify to: local filesystems (read/write files), GitHub (repos, PRs, issues), Slack (messages, channels), PostgreSQL databases, web browsers (Puppeteer), web search (Brave, DuckDuckGo), and any custom service with an MCP server.

Do I need to code to use MCP with Dify?

For official MCP servers (filesystem, GitHub, etc.), you only need to run a single npx command to start the server, then add the URL in Dify. No coding required. Building a custom MCP server requires basic Node.js or Python knowledge.

Is MCP secure for production use?

MCP security depends on your server configuration. Always run MCP servers on localhost or a private network — never expose them directly to the internet. Use authentication tokens and limit file system access to specific directories. For production, run MCP servers on the same private network as your Dify instance.

Ready to Run Dify + MCP in Production?

MCP is most powerful when self-hosted alongside Dify — both on the same private server, with no data leaving your infrastructure. Hetzner gives you a VPS from €3.79/month with the performance to run Dify and multiple MCP servers simultaneously. Or use Elestio for a fully managed, one-click Dify deployment.

Deploy on Hetzner (from €3.79/mo) → 1-Click Deploy on Elestio Compare All Hosting Options

Common Mistakes and How to Avoid Them

1. Incorrect MCP Server URL

Many users mistakenly configure the MCP server URL incorrectly. This usually results in connection errors like:

ConnectionError: Unable to connect to MCP server at http://localhost:8080

To fix this, ensure the URL in your Dify configuration file (config.yaml) matches the actual MCP server endpoint.

2. Missing Required Permissions

Users often forget to set the necessary permissions for the tools they want to access. This can lead to error messages such as:

PermissionDenied: You do not have access to this tool

Check the permissions in your MCP server configuration and ensure that the Dify agent has the required access rights.

3. Incompatible Tool Versions

Using outdated or incompatible versions of tools can lead to unexpected behavior. Symptoms include:

ToolError: Unsupported tool version

Always verify that the tools you are connecting to are compatible with the MCP version you are using.

4. Misconfigured Network Settings

Network issues can prevent Dify from reaching the MCP server. Look for errors like:

NetworkError: Unable to reach MCP server

Ensure that firewalls and security groups allow traffic on the MCP server's port (default is 8080). Use telnet to test connectivity.

Advanced Configuration

1. Connection Pooling

To improve performance, enable connection pooling in your MCP server configuration. This reduces latency by reusing existing connections.

connection_pool:
  max_connections: 20
  timeout: 30

2. Custom Timeout Settings

Adjust the timeout settings for tool requests to avoid premature failures. Set a higher timeout for tools that may take longer to respond.

tool_timeout: 120

3. Logging Level Adjustment

Modify the logging level to capture more detailed information for troubleshooting:

logging:
  level: DEBUG

Troubleshooting Checklist

Run docker compose logs api | tail -50 and look for any error messages related to connection issues.
Check the MCP server status with curl http://localhost:8080/health to ensure it is running.
Verify the configuration file (config.yaml) for any syntax errors using yamllint config.yaml.
Test the connection to the MCP server using telnet localhost 8080 to confirm network accessibility.
Inspect the tool permissions in the MCP server configuration to ensure they align with your Dify agent's requirements.