How Dify MCP integration works in both directions
Dify supports Model Context Protocol in two directions, and a team usually needs only one at first. Inbound, Dify acts as an MCP client: an agent or workflow in Dify calls tools hosted on an MCP server you run, such as an internal ticketing or inventory service. Outbound, Dify acts as an MCP server: a Dify app is published so that an outside AI client, such as Claude Desktop or Cursor, can call it. Decide which direction serves the use case before you touch either setting, because each one brings different credentials, owners and data exposure.
For import, only MCP servers that use HTTP transport are supported, and each server is added by its URL, a display name and a unique server identifier. Dynamic Client Registration is on by default and obtains OAuth credentials automatically, while a manual client ID and secret or custom headers are the alternatives. Confirm with your identity team which method your MCP server accepts before you build against it, and confirm any transport other than HTTP with the Dify documentation for your version, since this page does not cover it. Apps refer to a server by its identifier, so treat that identifier as a stable name from the start.
For publishing, the feature is off by default and is enabled on the app's Access Point tab. The generated server URL carries authentication credentials, so handle it like an API key: store it in your client's secret store, limit who can see it, and plan a rotation path. Regenerating the URL immediately invalidates the old one, which will stop every client that still uses it. Decide in advance which clients are approved and who owns the rotation, because a leaked URL gives callers the app's capabilities until you regenerate it.
What you need before connecting an MCP server
Connecting an MCP server to Dify and publishing a Dify app as one both depend on the same base: a supported self-hosted version, a reachable endpoint, the right credentials and workspace permissions. Confirm each item below before you open the Tools page, because most failed connections trace back to one of them.
Self-hosted Dify version and host
Confirm which Dify release your instance runs and plan upgrades against the release notes, since MCP-related behavior has changed across minor versions. The Docker Compose deployment expects at least 2 CPU cores, 4 GB of RAM and Docker Compose 2.24.0 or later. Check the version in your console before you follow any steps in this topic, and record it with your change ticket.
HTTP-transport MCP server with a URL
Dify's tools docs say only MCP servers using HTTP transport are supported, and servers are added by URL, a display name and a unique server identifier. Stdio-only servers will not connect directly. Confirm that the server exposes an HTTP endpoint your Dify host can reach, and choose the identifier now, because apps reference tools by that identifier and renaming it later breaks them.
OAuth or header credentials
Dynamic Client Registration is on by default and obtains OAuth credentials automatically, but it only works if the MCP server's authorization server supports it. Otherwise you need a manually issued client ID and secret, or custom headers carrying a token. Confirm DCR and OAuth support with the MCP server's vendor before you plan around it, and ask which scopes and token lifetimes apply.
Workspace roles for tools and publishing
Adding MCP servers and publishing apps are workspace permissions, so the people doing the work need roles that allow them. Decide who may add or change tool servers and who may enable the Access Point and regenerate MCP server URLs. Keep these roles narrow, because a generated MCP URL carries credentials and whoever holds it can call the app.
Outbound paths through the SSRF proxy
Dify routes outbound requests through an SSRF proxy that blocks internal and private IP ranges, so an MCP server on a private address may be unreachable even when the network allows it. Test the path from the Dify api container, not from your laptop. If the server sits on an internal host, plan the proxy allowlisting with your network team and document each host you open.
Secrets and key planning
The SECRET_KEY value encrypts OAuth credentials stored by Dify, and changing it after deployment logs out all users. Confirm the value is set and backed up before you store MCP client secrets. Agree on who owns each MCP credential, when it rotates, and where the copy of a regenerated app URL is recorded, since regenerating it invalidates the old URL immediately.
Configuring the import and publishing sequence
This sequence connects Dify to an external MCP server so its tools can be attached to apps, then publishes a Dify app as an MCP server that a client can reach and list tools from. Each step ends with a check so the team knows the connection holds before moving on.
Confirm the server uses HTTP transport
Before anything is configured, the platform team confirms with the MCP server owner that the server speaks HTTP transport and obtains its full endpoint URL. Dify's tools documentation states that only MCP servers with HTTP transport are supported, so a server that only runs over other transports cannot be imported at all. Confirm the URL resolves from the Dify API and worker containers, not only from a laptop, because outbound requests from Dify pass through the SSRF proxy. The step is done when the owner has supplied the exact URL and confirmed the transport in writing.
Add the server with a name and identifier
A workspace administrator adds the MCP server in the Dify tools area by entering its URL, a display name and a unique server identifier. The identifier matters more than the name: apps reference an MCP server by this identifier, so changing it later breaks tools in every app that uses it. Pick a stable, descriptive value and record it in your configuration notes so exported apps can be recreated in other workspaces with the same identifier. The step is done when the server appears in the list with its identifier saved.
Choose the authorization method
Choose how Dify authenticates to the server. Dynamic Client Registration is on by default and obtains OAuth credentials automatically, which suits servers that support it. If the server does not support dynamic registration, enter a client ID and client secret issued by the provider, or add custom headers when the server expects a static token. Ask the server owner which method they support and who owns the credential lifecycle, since the chosen method determines where secrets are stored and how they are rotated. The step is done when the authorization completes without an error on the server card.
Verify the tool listing loads
After authorization, open the server's tool list and confirm the expected tools appear with their names and descriptions. This is the first real test of the connection: an empty list or an authorization error usually points to a wrong URL, a header the server rejects, or a registration the provider has not accepted. Check each tool that the planned apps need, not only the count, because a tool missing from the list will be missing from every app that depends on it. The step is done when the full set of required tools is listed.
Attach the tools to an app
Open the application in the workflow or agent configuration and add the imported MCP tools that it needs. Attach only the tools the app's purpose requires, since each tool gives the model a capability that can read or change data in the external system. Run a test prompt in the debug view to confirm the model calls the intended tool and receives a result. The step is done when a test run shows a successful tool call with an expected response from the external server.
Enable publishing on the Access Point tab
Open the app's Access Point tab and enable publishing as an MCP server. Publishing is off by default, so this is a deliberate decision by the app owner, and it should be recorded alongside the reason the app is exposed. Dify generates a server URL that contains authentication credentials, so handle it as you would an API key: store it in a secrets manager, not in a shared document. The step is done when the Access Point shows an active MCP server URL for the app.
Test the generated URL from a client
Connect a client such as Claude Desktop or Cursor to the generated URL using the client's MCP configuration, then confirm the client lists the app's tools. Test a single tool call with a harmless input so you know the call path works end to end. Before you hand the URL to users, record who holds it, since regenerating the URL immediately invalidates the old one and every client using it stops working until it is updated. The step is done when a client lists the tools and completes one test call.
Choosing OAuth dynamic registration, manual OAuth or custom headers
Dynamic Client Registration is on by default in Dify's tool settings for MCP servers. Dify registers itself with the upstream authorization server and receives a client ID and secret without an administrator copying them by hand. The secret is held by Dify, and the upstream provider records the registration. This suits teams that want the least manual handling, but the trade-off is that the upstream server must support dynamic registration and you must confirm that it does before you rely on it.
- Who holds the secret: Dify holds the credentials it receives. Your administrators usually never see them, so access reviews must look at the workspace that owns the tool.
- Storage: Dify stores OAuth credentials encrypted with the workspace secret key. Changing
SECRET_KEYafter deployment logs users out and affects how stored credentials are read, so plan that change deliberately. - Rotation: Rotation depends on the upstream provider. Ask whether it expires registrations or revokes them, and whether re-authorization happens without manual steps.
- What breaks: If the provider disables dynamic registration, rotates its authorization settings or changes its scopes, tools stop working until the server is re-added or re-authorized.
- Confirm first: Ask the provider whether dynamic registration is enabled for your tenant and which scopes the registration receives.
Before approving this option, confirm the upstream provider's registration policy and who can remove registrations.
Manual OAuth uses a client ID and client secret that your team creates in the upstream provider and enters in Dify. The provider's administrator owns the application, and your platform team owns the copy stored in Dify. This option gives you control over the registration, scopes and audit trail, which many identity teams prefer, at the cost of a secret that must be tracked and renewed.
- Who holds the secret: Two parties hold it: the provider administrator who created the client and the Dify administrators who entered it. Record both owners.
- Storage: The secret is saved in Dify's tool configuration and encrypted with the workspace key. Limit who can open tool settings, since editing them exposes configuration to that role.
- Rotation: Rotate the client secret in the provider, then update the entry in Dify. Schedule this as a change so apps that depend on the server are not interrupted without notice.
- What breaks: An expired or rotated secret causes authorization failures, and tools in every app that references the server fail together.
- Confirm first: Check whether the provider issues secrets with expiry dates and how it notifies owners before they lapse.
Keep a record of which application in the provider corresponds to which Dify server identifier.
Custom headers let Dify send a static header with each request to the MCP server, such as an API key or bearer token issued outside OAuth. This is the simplest option for servers that do not support OAuth flows, but it places a long-lived credential directly in configuration. The security posture depends almost entirely on how that credential is issued, scoped and rotated.
- Who holds the secret: The party that issued the token holds it, and Dify holds a copy. Confirm whether the token is tied to a service account or a person, since personal tokens leave when that person leaves.
- Storage: Header values are stored in Dify's tool configuration. Treat them like any other secret in your secret management process and avoid pasting them into shared documentation or exported files.
- Rotation: Rotation is manual unless the provider offers automated issuance. Plan an update in Dify for every rotation.
- What breaks: When the upstream provider changes its token format, header name or expiry rules, requests fail with authorization errors across all apps using the server.
- Confirm first: Ask whether the token can be restricted to specific tools and whether it is logged on the provider side.
Avoid broad tokens with write access when a read-only scope will do for the workflows involved.
The other direction carries its own credential. When you publish a Dify app as an MCP server, the generated server URL contains authentication credentials. Publishing is off by default and is enabled on the app's Access Point tab. Anyone who holds the URL can connect to the app, so the URL must be handled like an API key, not a public link.
- Who holds it: Whoever configures the client, such as a developer's Claude Desktop or Cursor setup, holds a copy. Track which people and machines have it.
- Storage: Store the URL in the client's secure configuration and keep it out of source control, tickets and chat channels.
- Rotation: Regenerating the URL immediately invalidates the old one. Plan the cutover with every user who connects, because their clients stop working at once.
- What breaks: A leaked URL lets an unauthorized party invoke the app. Regeneration is the response, and it also disconnects legitimate clients.
- Confirm first: Decide who may enable publishing and who may regenerate URLs, and record the owner of each published app.
Review published apps periodically and disable publishing for any app that no longer needs it.
The three import options and the published URL answer different questions. Dynamic registration minimizes manual secret handling but depends on the upstream provider supporting it. Manual OAuth gives the provider's administrators control over the application and its secret. Custom headers are simplest but leave a static credential in configuration that someone must rotate by hand. Choose based on what the upstream server supports and which team will own rotation.
- Match the provider: Start with what the MCP server supports, since not every server offers OAuth registration.
- Name an owner: Assign one team to rotation and revocation for each server, and record it.
- Scope access: Prefer read-only or narrowly scoped credentials wherever the workflow allows.
- Plan for breakage: Document how each option fails and who responds, including the apps that reference the server identifier.
- Protect the published URL: Apply the same controls to the URL you generate for clients as to any API key.
Before going live, confirm the rotation procedure for each credential with the team that will operate it.
Mapping MCP server identifiers, apps and client configurations
This table maps each MCP object in a self-hosted Dify to the objects that depend on it, so you can see what breaks when an identifier, export or credential changes. Read each row as a dependency: the left column is the object you change, and the right columns show what must be updated alongside it. The main takeaway is that identifiers and published URLs are the two values most likely to break working integrations.
| Object | Depends on it | What changes it breaks or requires | Owner to confirm |
|---|---|---|---|
| MCP server identifier | Apps that call tools from that server | Changing the identifier breaks tools in every app that references it | Dify workspace admin |
| MCP server URL and auth | Dify tool connection to the HTTP MCP server | Rotating OAuth credentials or headers requires updating the server entry before tools resume | Integration owner of the external server |
| App export (DSL file) | Target workspace in another Dify instance | Export excludes server connections, so matching servers must be recreated with identical identifiers | App builder and target workspace admin |
| Published MCP server URL | Claude Desktop or Cursor client configuration | Regenerating the URL immediately invalidates the old one, so every client config must be updated | App owner who published the app |
| Client configuration file | Users running Claude Desktop or Cursor on their machines | Each user holds a copy of the URL, so a rotation needs a coordinated update across all copies | Desktop or IDE administrator |
| Credential owner | OAuth client or header secret for the MCP server | Departure of the owner can strand tool access, so record who can rotate each secret | Named internal owner recorded in your register |
| Rotation procedure | Published URLs and stored OAuth or header secrets | Rotate in a planned window: update the target, then notify clients, then retire the old value | Security team with the app owner |
How the tool calls and published URLs flow
Two separate request paths exist, and each one carries its own credential. In the first, an agent running inside a Dify workflow or agent node calls a tool that was imported from an external MCP server. Dify's own runtime makes that outbound call over HTTP to the server URL you registered, and the server authenticates the call with whatever Dify holds for it: the OAuth access token obtained through Dynamic Client Registration, a manually entered client ID and secret, or the custom headers you configured. The MCP server, not Dify, decides what that credential may do, so scope the token or header value to read-only or the narrowest action the agent needs. Confirm with the MCP server's owner which scopes the issued token carries, because Dify does not manage those on your behalf.
In the second path, an external client such as Claude Desktop or Cursor connects to the server URL that Dify generates when you enable MCP on an app's Access Point tab. That URL embeds the authentication credential, so it functions like an API key: Dify checks it on each connection and the app's own settings still determine which tool it exposes. Copy the URL only into the client configuration that needs it, and record which people or machines hold it, since Dify does not show you a list of who connected.
Regenerating the URL is the step most likely to cause an outage. The old URL stops working immediately, with no grace period, so every client still using it will fail on its next connection. Plan a regeneration as a change with a named owner: list each client that holds the URL, schedule the update across all of them in the same window, regenerate, then update and test each client before you close the change. Clients that cache a failed connection may need a restart before they pick up the new URL, so include that in the test steps. Confirm the exact behavior of your Dify version against the Dify MCP server docs before relying on it.
Securing MCP credentials and exposed app URLs
Both directions of MCP in Dify move credentials across a boundary: outbound tokens and client secrets for MCP servers you import, and inbound URLs that carry authentication for apps you publish. The cards below cover where those secrets live, what SECRET_KEY and the SSRF proxy do to them, how tool scope limits damage, and how to rotate a published URL without breaking clients.
Protect OAuth client secrets and header tokens
Dify can register with an MCP server automatically through Dynamic Client Registration, or accept a manual client ID and secret, or custom headers. Each path stores a credential inside the Dify workspace. Decide per server which path applies, record who created each credential, and keep the value out of exported DSL files and shared runbooks. Confirm in your own environment that rotated tokens are updated in Dify and not only at the MCP server, since a stale header fails silently for users.
Understand SECRET_KEY before changing it
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, including the credentials Dify holds for MCP servers. Changing it after deployment logs out all users, and the environment reference does not describe a supported path for re-encrypting stored OAuth credentials, so treat the value as permanent. Generate it once, store it in your secrets manager, back it up with the database, and confirm with your vendor how a restore onto a new host handles it.
Plan SSRF proxy rules for internal MCP servers
Dify routes outbound requests through an SSRF proxy that blocks internal and private IP ranges. An MCP server on a private network or a corporate host will therefore be unreachable by default. Allowlisting it is a deliberate exposure decision: name the exact host and port, avoid broad CIDR ranges, and record the owner of each allowlisted destination. Confirm with your vendor which proxy setting controls the allowlist in your release, since the mechanism is set through configuration rather than the Dify console.
Isolate agent sandbox network access
The Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy, along with token-based API authentication between services. Confirm that your deployed version includes these changes before relying on them, and check that sandboxed tool calls cannot reach internal addresses that the SSRF proxy would otherwise block. Test an agent that tries to call a private host to see which layer stops it.
Scope tools to least privilege
An MCP server often exposes more tools than a given app needs. Import only the tools a workflow uses, prefer read-only scopes for the MCP server's own credential, and give each server a separate identity rather than a shared administrator token. Review agent instructions so the model is not offered write actions it does not need. Apps refer to servers by identifier, so keep identifiers stable and documented when you rotate scopes.
Treat published app URLs as API keys
Publishing an app as an MCP server is off by default and is enabled on the app's Access Point tab. The generated server URL carries authentication credentials, so store it like an API key, restrict who can view it, and never place it in a ticket or a shared document. Regenerating the URL immediately invalidates the old one, so schedule the change, update every client such as Claude Desktop or Cursor, and then confirm the old URL returns an error.
Why MCP tools fail to load or publish
This table lists the failures teams hit when importing MCP tools into Dify or publishing an app as an MCP server, with the likely cause and fix for each. Read it when a server will not connect, tools disappear, or a client suddenly stops working. Confirm the server-side details with the MCP server vendor before changing Dify settings.
| Failure | Likely cause | Fix and what to confirm with the vendor |
|---|---|---|
| Server will not add | Server uses an unsupported transport such as stdio or SSE instead of HTTP | Dify supports only HTTP transport. Confirm with the vendor that an HTTP endpoint exists before retrying, or use a different server. |
| OAuth credentials not created | Dynamic Client Registration is disabled or refused by the authorization server | Enable Dynamic Client Registration, or enter a client ID and secret manually. Ask the vendor whether dynamic registration is supported and which client credentials to issue. |
| Authorization fails after redirect | Redirect URI or requested scope does not match what the authorization server allows | Compare the redirect URI and scopes Dify sends with those registered for the client. Ask the vendor for the exact scopes the tools require. |
| Custom header authentication rejected | Header name, prefix or token value is wrong, or the token has expired | Check the header name and token format against the vendor's documentation, then reissue the token. Ask the vendor about token lifetime and rotation. |
| Internal MCP server unreachable | SSRF proxy blocks requests to internal or private IP ranges | Allowlist the server through the SSRF proxy settings in your deployment, scoped to that host only. Confirm with your network team which address the server uses. |
| Tools missing or apps show errors after a rename | The server's unique identifier was changed, so apps no longer resolve it | Restore the original identifier. Apps reference servers by identifier, so ask the team that owns the server to keep identifiers stable. |
| Client stops connecting after an update | The app was regenerated or its published URL was replaced, which invalidates the old URL | Distribute the new URL to every client and treat it like an API key. Record who holds the URL so rotations are coordinated. |
| Imported app has no tools | Exported DSL does not carry the servers, so the target workspace lacks them | Recreate each MCP server in the target workspace with the same identifier, then re-check tool bindings. Confirm credentials are issued separately in that workspace. |
Questions buyers ask about Dify MCP integration
How much effort does Dify MCP integration take, and what drives it?
Effort depends mostly on how many MCP servers you import, how many Dify apps depend on them, and how many credential models you must handle. Importing one HTTP MCP server with Dynamic Client Registration is a small task. Multiple servers with manual OAuth client IDs, custom headers, and per-workspace setup add review and testing work. Publishing apps as MCP servers adds access review for each generated URL. Ask any partner for a written scope that lists each server, each app, each credential method, and each target workspace, since those items set the quote.
Can our team set up Dify MCP integration without a partner?
Yes, a team with Dify administration experience and access to the MCP server owners can do this in-house. Dify supports only MCP servers with HTTP transport, adds them by URL, name and a unique server identifier, and handles Dynamic Client Registration automatically when it is enabled. The work that tends to need outside help is designing identifiers that will survive export and import, deciding which apps may be exposed, and writing the credential handling and review steps your security team expects. Your own staff keep that knowledge after the project ends.
What must our team provide before the work starts?
Plan to provide the owner or administrator of each MCP server, the OAuth application details if you use manual client credentials, and the header values or secrets for servers that use custom headers. You also need approval for outbound network paths from your Dify host to each server, and any proxy allowlisting your network requires. On the publishing side, name the business owner for each app that will be exposed, and the people who will receive generated server URLs. Confirm each item with the server owners before scheduling tests.
How long do testing and rollout take as the number of servers and apps grows?
Duration grows with the number of servers, the number of apps that reference each server, and the number of workspaces involved. Each server needs a connection test, a tool listing check, and a run of each dependent app. Each published app needs a client test from the actual MCP client, such as Claude Desktop or Cursor. No timeline is fixed in this page, so ask for a duration in the written scope based on your inventory of servers, apps and environments.
Does Dify Enterprise change how MCP integration works?
The MCP server import and app publishing steps described in the Dify docs are the same for the self-hosted Community edition and the self-hosted Enterprise edition as far as these sources show. Enterprise adds SSO with OpenID Connect, SAML and OAuth2, multiple workspaces, and professional support, which affect who can manage tools and apps. Confirm with Dify whether any MCP behavior differs in your edition before you rely on it. Enterprise pricing is custom, so the commercial decision needs a written quote.
What happens to published MCP URLs and imported tools during upgrades?
Published MCP server URLs contain credentials and should be handled like API keys. Regenerating one immediately invalidates the old URL, so clients using it stop working until they receive the new one. During upgrades, back up before you start, follow the upgrade guide for the target version, and check .env.example for new variables. Apps reference MCP servers by identifier, so keep identifiers unchanged across upgrades and exports. After each upgrade, verify that imported tools still list and that each published URL still connects.
How should we handle credentials for MCP servers and published apps?
Store OAuth client secrets and custom header values as secrets, limit who can view or edit them, and review them on a schedule. Dynamic Client Registration removes manual client secrets when a server supports it, but you still need to review which servers are trusted. Treat each published app URL as a credential: share it only with named clients, and regenerate it if it leaks. Your security team should review these controls against your access policy before rollout.
How DeployOpen scopes and delivers Dify MCP integration
DeployOpen plans, builds, documents and supports self-hosted Dify inside your own infrastructure, including MCP tool imports and app publishing. We start from a written scope that names each MCP server, each app exposed to MCP clients and the credential method each one uses.
How we scope
- Inventory every MCP server Dify must reach, its URL, transport and whether it uses OAuth or custom headers.
- List each Dify app to be published as an MCP server, with the clients that will connect to it.
- Record the server identifiers apps depend on, so renames and workspace moves do not break tools later.
How we build
- Register tool servers with Dynamic Client Registration, a manual client ID and secret, or custom headers, as the server requires.
- Enable app MCP publishing on the Access Point tab only for approved apps, and document who holds each generated URL.
- Test each tool call end to end, including failure paths when a credential is expired or a server is unreachable.
How we hand over
- Deliver a written record of each MCP server, identifier, credential method and owner, stored outside the Dify console.
- Document the regeneration procedure for published MCP URLs, including which clients must be updated when one is replaced.
- Provide runbooks for recreating servers with matching identifiers when an app is exported and imported into another workspace.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, Dify upgrades and continuous testing are available as a retainer, which covers MCP changes between releases.
- Confirm with your team which MCP servers and clients are in scope for each retainer period before any change is made.
