How to Add Web Search to Dify Apps With You.com

TLDR: Dify can reach You.com two ways. Add the You.com MCP server (https://api.you.com/mcp) under Integrations > Tools with an Authorization header, which gives agents a search tool and a page-reading tool, or import the Web Search API as a custom tool from a short OpenAPI schema. Authenticating the MCP route with a key needs Dify 1.9.0 or later. On the schema route, set the header prefix to Custom or Dify sends the wrong header.

Dify is an open-source platform for building AI apps, and its tools documentation lists four ways to make a service callable: a tool plugin, a Swagger (OpenAPI) import, a workflow published as a tool, and an MCP server. This guide covers the two that reach You.com, with the details the docs leave out: what goes in each credential field, how Dify picks an MCP transport, and how to keep search results from swamping the model's context. Facts come from the Dify docs and source code, the You.com MCP docs, and live calls to the keyless profile on October 5, 2026.

What Does Dify Offer for Web Search Out of the Box?

The Marketplace carries search plugins, including Tavily, SearXNG, Bing, Brave, and Serper. A Marketplace search for You.com returned no You.com plugin on October 5, 2026, so the Marketplace is not the route here. That leaves two, and Dify's Integrations page names both under tools: "MCP servers" and "OpenAPI services".

Should You Use the MCP Server or an API Tool?

	MCP server	API tool (Swagger API)
What the agent gets	Every tool the server exposes: four by default, including you-search and you-contents	One action, the search call
Setup	URL, name, identifier, one header	Paste a schema, fill the credential form
Dify version	MCP in 1.6.0, OAuth in 1.8.0, custom headers in 1.9.0	Any release with custom tools
Where you control inputs	Headers on the server entry	The schema and the node's tool settings
Best for	Agents that search, then read the pages they pick	A fixed, typed search step in a workflow

The version row comes from the Dify release notes: 1.6.0 introduced MCP support, 1.8.0 added OAuth for MCP, and 1.9.0 added MCP server headers. If you self-host an older release, the schema route is the one that works with a key. Dify's docs also note that only MCP servers with HTTP transport are supported, which the You.com remote server is.

How Do You Add the You.com MCP Server in Dify?

Open Integrations > Tools, go to the MCP section, and choose Add MCP Server (HTTP). Fill in the form with the values below, using a key from the You.com platform:

Dify field	Value
Server URL	https://api.you.com/mcp
Name & Icon	You.com
Server Identifier	youcom (lowercase letters, numbers, underscores, and hyphens, up to 24 characters)
Headers	Header Name Authorization, Header Value Bearer YOUR_YDC_API_KEY

Choose Add & Authorize. Dify connects, imports the server's tools, and shows the count on the server card. The bare endpoint exposes four: you-search, you-contents, you-balance, and you-discover.

Keep the URL path ending in /mcp. Dify chooses the transport from the last segment of the path: /mcp goes straight to streamable HTTP, /sse goes to SSE, and any other ending, such as /mcp/research, makes Dify try SSE first and then fall back to streamable HTTP. To add research or limit the list, use the tools query parameter on /mcp, as the MCP docs describe, instead of a different path.

To try the integration without a key, enter https://api.you.com/mcp?profile=free and no header. It exposes you-search and you-discover at 100 queries a day. If you would rather not store a key at all, the bare URL answers an unauthenticated request with a 401 and an OAuth challenge, and You.com's authorization server publishes a registration endpoint, which is what Dify's default Dynamic Client Registration looks for. This guide uses a key because headers are the path Dify documents for static tokens.

Check the endpoint from a terminal before blaming Dify. This command lists the tools on the keyless profile:

curl -s -X POST "https://api.you.com/mcp?profile=free" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | grep -o '"name":"you-[a-z-]*"'

How Do You Import the Web Search API as a Custom Tool?

Open Integrations > Tools, go to Custom, and choose to create a custom tool. Name it, then paste this schema into the Schema field:

{
  "openapi": "3.0.0",
  "info": {
    "title": "You.com Web Search",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "https://ydc-index.io"}
  ],
  "paths": {
    "/v1/search": {
      "post": {
        "operationId": "webSearch",
        "summary": "Search the live web. Returns ranked results in results.web and, for news-like queries, results.news. Use it for current events, recent releases, and facts that may have changed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "One search query in plain language, such as: dify mcp server http transport"
                  },
                  "count": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum results per section, 1 to 100"
                  },
                  "freshness": {
                    "type": "string",
                    "description": "Optional recency window: day, week, month, year, or a range such as 2026-09-01to2026-10-05"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {"description": "Ranked web and news results as JSON"}
        }
      }
    }
  }
}

Dify turns each property of the request body into a tool input, uses the operation's description (or its summary, when there is no description) as the text the model reads, and sends a property's default when the model leaves it out. Run through Dify's own parser code, this schema yields three inputs: query (a required string), count (a number defaulting to 5), and freshness (a string).

Why not import You.com's published spec by URL? The full OpenAPI 3.1 file for the Web Search API lives at https://you.com/docs/openapi/web-search.json, and the openapi.json address in the docs index is an HTML page that links to it. Dify's parser accepts that file but does not resolve properties that are references, so in a test it produced 15 inputs, all typed as strings, none with a description, count and offset included. Its 1,272-character endpoint description, markup tag and all, also becomes the tool description the model reads. A short hand-written schema avoids all three problems.

The credential is the step that trips people up, because Dify ignores the schema's security scheme and uses its own form. Set Authorization method to Header, enter X-API-Key as the Key, paste your You.com key as the Value, and set Auth Type to Custom. The form starts on Basic, and Dify's code prepends the word Basic to the value, so a default form sends X-API-Key: Basic YOUR_KEY. Custom sends the value unchanged. Then use Test on the action in the Available Tools table with a short query before you save. To check the key outside Dify, the cURL guide sends the same request.

To stop the model from choosing result counts, set count to manual input in the Agent node's tool settings. The docs describe each tool parameter as either auto-generated by the agent or entered by you as a fixed value. Or drop count from the schema and accept the API's default of 10 results per section.

How Do You Use the Tool in a Workflow or Agent?

The docs list three places a tool can run: a Tool node in a workflow or chatflow, an Agent node, and Agent apps. In a workflow, choose Add Node > Tools and select the action. The right node depends on who decides when to search. A Tool node always fires, with a query built from upstream variables, so use it when the flow should always search. An Agent node lets the model decide, using a function-calling or ReAct strategy, so use it when only some requests need fresh data. The agent tool calling guide covers that tradeoff for any framework.

Three Agent node settings matter for search. The tool description guides when the model calls it, and the docs list clear descriptions as a best practice, so keep the summary in the schema specific. Max Iterations caps the loop; the docs suggest 3 to 5 for simple tasks and 10 to 15 for complex research. And in the instructions, say when search is appropriate, because a cheap tool invites searches the conversation already answers. The custom tool returns the parsed JSON and the raw response text, so downstream nodes read results.web and results.news from the JSON; the response guide documents each field.

How Do You Keep Search Results Small?

On the MCP route, the you-search tool defaults to highlights and up to 30 results per section. Dify's Headers list can pin X-Search-Count and X-Search-Extraction, and a pinned value wins over what the model sends. In one test on the keyless profile on October 5, 2026, five results took 34,766 characters with highlights and 9,266 with extraction set to none. Extraction none returns snippets only, so keep you-contents available when you use it. On the API route, the REST endpoint returns snippets by default, and the schema's default for count caps the number of results. On that route the bill does not move: as of October 2026 the Web Search API bills $5.00 per 1,000 calls with up to 100 results per call, so count saves context, not money.

What Fails, and How Do You Spot It?

The header field is missing or the key is ignored. Releases before 1.9.0 have no MCP server headers. Upgrade, or use the schema route.

A 401 from the API tool with a correct key. Check Auth Type. Basic turns the key into Basic YOUR_KEY, which is not what the API expects.

The run log shows a status code and a body. Dify reports API failures as "Request failed with status code" followed by the code and the response text. In the OpenAPI spec, 401 means a problem with the key, 402 means the account cannot make paid API requests, 403 means the key lacks scope for the path, and 422 means an invalid parameter combination.

Apps lose the tools. Apps reference an MCP server by its identifier, so renaming it breaks them, and Dify warns that updating the tool list can affect existing apps. Pick the identifier once.

The connection is slow on a custom path. A URL that does not end in /mcp or /sse makes Dify try SSE before streamable HTTP. Keep the URL ending in /mcp.

The agent over-searches. Lower Max Iterations, tighten the instructions, or move the search to a Tool node.

Example verification: Dify's own parser and request code, run from its GitHub source with stubbed model classes and a stubbed HTTP layer, produced the three inputs above and the request headers and body described in this guide, including the Basic prefix behavior. Dify's MCP handshake was replayed with httpx against the keyless profile: initialize returned 200 with no session ID, notifications/initialized returned 202, and the tool list came back with you-search and you-discover. Dify opens its optional GET stream only when a server issues a session ID, so it skips that step here. No Dify instance was run, and no keyed call was made, so form labels and the keyed MCP path follow the docs and source rather than a live session.

Related Guides

• How to Set Up the You.com MCP Server for Web Search in Any Client
• How to Call the You.com Web Search API With cURL
• What Is in a Web Search API JSON Response? Fields, Parsing, and Pitfalls
• How to Add Web Search to Agent Tool Calling With the You.com Web Search API
• What Is the You.com Web Search API? Endpoint, Pricing, and Limits