Integrate an OpenAPI MCP Server with Dify

Step 1: Set up a Dify server

This example shows how to set up a Dify server on an ECS instance.

1. Install Docker on the ECS instance.

2. Download the Dify code:

   git clone https://github.com/langgenius/dify.git

3. Modify the Dify configuration file:

   cd dify/docker
   cp .env.example .env
   vim .env

   In the .env configuration file, find the following parameters and set their values:

   Note

   These values must match the callback address of your OAuth application.

   Parameter	Value
   CONSOLE_API_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.
   CONSOLE_WEB_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.
   SERVICE_API_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.
   APP_API_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.
   APP_WEB_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.
   FILES_URL	http://<Public IP address or domain name of the ECS instance>. If you are deploying locally, use http://127.0.0.1.

4. Start the Dify server:

   # Stop Dify 
   # docker compose down 
   # Start Dify
   docker compose up -d

   The following output indicates that the Dify server has started successfully. If an error occurs, run docker compose up -d again until the following output appears.

   [+] Running 13/13
    ✔ Network docker_ssrf_proxy_network  Created
    ✔ Network docker_default             Created
    ✔ Container docker-ssrf_proxy-1      Started
    ✔ Container docker-redis-1           Started
    ✔ Container docker-db-1              Healthy
    ✔ Container docker-web-1             Started
    ✔ Container docker-weaviate-1        Started
    ✔ Container docker-sandbox-1         Started
    ✔ Container docker-worker_beat-1     Started
    ✔ Container docker-api-1             Started
    ✔ Container docker-plugin_daemon-1   Started
    ✔ Container docker-worker-1          Started
    ✔ Container docker-nginx-1           Started

Step 2: Create an OAuth application

Create an application on the OAuth Applications page of the Resource Access Management (RAM) console. Note the following parameter settings:

Step 3: Create an OpenAPI MCP Server

When creating an MCP Server in the Alibaba Cloud OpenAPI MCP service, set OAuth configuration to Custom OAuth and select the OAuth application that you created. If you are using an existing MCP Server, change its OAuth configuration to Custom OAuth and select your application. After you select Custom OAuth, the OpenAPI MCP Server uses your OAuth application for authorization, redirecting the authorization code to your self-hosted Dify service.

Step 4: Add an OpenAPI MCP Server to Dify

1. In a browser, navigate to the Dify homepage at http://<Public IP address of the ECS instance>, follow the on-screen instructions to complete the setup, and then log in to Dify.

2. Navigate to Tools > MCP and add an MCP service. For Server URL, enter the Streamable HTTP Endpoint provided by your Alibaba Cloud OpenAPI MCP Server.

   After adding the service, wait for the automatic authorization to complete. If successful, the MCP service card turns green and displays an online status.

   In the details panel on the right, the service status is Authorized, and the panel lists the available ECS tools, such as Ecs-20140526-DescribeRegions, Ecs-20140526-DescribeAvailableResource, Ecs-20140526-RunInstances, Ecs-20140526-DescribeInstanceStatus, and Ecs-20140526-DescribeInstances (7 tools in total).

Step 5: Configure a model in Dify

Dify supports major model providers such as Qwen, Deepseek, and OpenAI's GPT series. For more information, see Connect to a large language model.

1. Click your profile picture in the upper-right corner and select Settings.

2. In the Model provider section, install a model. This example uses Qwen. For more information about Qwen, see Select a model.

3. After installation, configure the model settings, including the API KEY, Dify's default reasoning model, and embedding model.

   Note

   The reasoning model must support tool calls, such as qwen3-max-preview or DeepSeek-R1.

   On the Model provider page, the Qwen provider shows an Unauthorized status. Click the Settings button next to it to complete the authorization configuration. Then, click the System model settings button at the top of the page to select the default reasoning model and embedding model.

Step 6: Test the MCP functionality

Create a simple agent application to test the capabilities of the OpenAPI MCP Server.

1. Create an agent application. For Application Type, select Agent.

   In the Create application panel on the left, click Create Blank App.

2. Add tools to the agent application and select the OpenAPI MCP Server you added to Dify.

   On the Orchestrate page, in the Tools section at the bottom, click + Add. In the tool pop-up, select the MCP category, find mcp_demo, and add all its tools. After adding, the Tools section displays 7/7 Enabled.

3. In the Debug & Preview interface, enter a natural language query, for example, "how many ECS instances are in China (Hangzhou)?"

   The AI assistant calls the DescribeInstances API with the parameters RegionId: cn-hangzhou and PageSize: 1, extracts the TotalCount field from the response, and returns the result: There is 1 ECS instance in China (Hangzhou).