How to Add Web Search to Windsurf With the You.com MCP Server

TLDR: Windsurf already has web search, so the case for adding the You.com MCP server is control: your own key, result caps and domain limits set in the config, and a server an admin can approve by name. Windsurf's docs now describe two agents with different MCP configs. Use devin mcp add for Devin Local, the default for new tabs, or mcp_config.json for the legacy Cascade agent, both pointing at https://api.you.com/mcp.

Windsurf's docs now refer to the editor as Devin Desktop and label Cascade the legacy agent, which changes where MCP servers are configured. This guide covers both agents. The server is the same either way: the hosted You.com MCP server at https://api.you.com/mcp. Our MCP server guide covers the client-agnostic setup, so this page sticks to what is specific to Windsurf. Details were checked on October 4, 2026 against the Windsurf, Devin CLI, and You.com MCP documentation and against the live server's keyless profile.

Does Windsurf already have web search?

Yes, in both agents. Cascade searches the web when a prompt needs it or when you write @web, reads pasted URLs, and answers @docs queries (Windsurf web and docs search). The Devin Local agent has its own web fetch and search tools, governed by the Devin CLI permission system. An MCP server does not add a missing capability. It changes who controls the search.

Three situations favor adding one. First, admins can turn built-in search off. Cascade's Enable Web Search admin setting removes the search tool server-side, so users cannot re-enable it, and for Devin CLI the same tool is disabled by default on enterprise teams (team settings docs). A server that an admin allowlists by name is a narrower thing to approve than open-internet search. Second, you want to bound and steer results, which the You.com server lets you do from the config headers. Third, you want the same search behind several tools, because this is the server you would also use from Cursor or Claude Code.

Which Windsurf agent are you configuring?

Check the agent selector before you edit any file. New tabs start with Devin Local unless you chose another agent, and existing Cascade conversations stay available in history (Devin Local docs). Cascade's MCP page says its setup applies to the legacy agent only, and that Devin Local reads the Devin CLI config files instead.

Setting	Devin Local (default for new tabs)	Cascade (legacy agent)
Where MCP is configured	Devin CLI config files	mcp_config.json, opened from the Cascade panel's Actions menu
User-level file	~/.config/devin/mcp_config.json, or %APPDATA%\devin\mcp_config.json on Windows	The same path
Other scopes	.devin/mcp_config.json (shared) and .devin/mcp_config.local.json (gitignored)	None documented
Remote server URL key	url	serverUrl or url
Keeping a key out of the file	Gitignored local scope, or OAuth with devin mcp login	${env:VAR} and ${file:/path} in headers
Marketplace and one-click install	Yes	No

Both pages name the same user-level path and both accept url, so write url in your entries and confirm the result in the MCPs section of whichever agent you use. Sources: the Cascade MCP page and the Devin CLI MCP configuration page.

How do you add the server to the Devin Local agent?

The CLI is the quickest route. It infers the transport from the URL and saves to local scope by default, a gitignored file at .devin/mcp_config.local.json. Quote the URL, because it contains a ?. Choose one of the first two commands:

# Option 1: keyless trial. Exposes you-search and you-discover, 100 queries per day.
devin mcp add youcom "https://api.you.com/mcp?profile=free"

# Option 2: OAuth, so no key sits in any file.
devin mcp add youcom https://api.you.com/mcp
devin mcp login youcom

# Check what is configured.
devin mcp list

The keyless profile exposes you-search and you-discover, limited to 100 queries per day. tools/list against the live profile on October 4, 2026 returned exactly those two. Use it to prove the wiring before you commit to a key.

For production there are two ways to authenticate. With OAuth, add the bare URL and run devin mcp login. The server answers an unauthenticated request with a 401 and a WWW-Authenticate challenge that points at its OAuth metadata, and that metadata advertises dynamic client registration with PKCE, which the Devin CLI docs say it uses automatically when a server supports it. Each MCP client keeps its own OAuth session, so signing in from another tool does not carry over. With an API key, save an entry like this in .devin/mcp_config.local.json, never in the shared .devin/mcp_config.json. The same entry carries two choices that matter later, a narrowed tool list and a result cap:

{
  "mcpServers": {
    "youcom": {
      "url": "https://api.you.com/mcp?tools=you-search,you-contents",
      "headers": {
        "Authorization": "Bearer YOUR_YDC_API_KEY",
        "X-Search-Count": "5"
      }
    }
  }
}

If you do not have the CLI, create that file by hand. MCP tool calls prompt for approval by default. To let the search tools run without a prompt, add an allow rule in .devin/config.json or ~/.config/devin/config.json (permissions docs). The pattern is mcp__<server>__<tool>, and the wildcard form covers one server, so scope the tool list first and the wildcard then covers only the tools you chose:

{
  "permissions": {
    "allow": ["mcp__youcom__*"]
  }
}

How do you add the server to the legacy Cascade agent?

Open the config from the Cascade panel: the ... Actions menu, then Open MCP config file in the MCPs section. The file is ~/.config/devin/mcp_config.json on macOS and Linux (or under $XDG_CONFIG_HOME when that is set) and %APPDATA%\devin\mcp_config.json on Windows. Cascade interpolates variables in url and headers, so the key can stay in an environment variable:

{
  "mcpServers": {
    "youcom": {
      "url": "https://api.you.com/mcp?tools=you-search,you-contents",
      "headers": {
        "Authorization": "Bearer ${env:YDC_API_KEY}",
        "X-Search-Count": "5"
      }
    }
  }
}

If the variable is not set in the environment Windsurf was launched from, the docs say it resolves to an empty string. The server then sees an empty Bearer token, and it answers that with a 401, the same as a missing header.

Three Cascade details are worth knowing. It allows 100 tools in total across servers; the MCPs section lists per-server counts, and a disabledTools array drops single tools. Enterprise users must turn MCP on in settings. And once an admin allowlists even one server, every other server is blocked for the team. The allowlist matches the key name in mcp_config.json exactly and is case-sensitive, so pick one name (youcom here) and give that string to your admin.

How do you keep search results small and scoped?

Two defaults surprise people. The MCP you-search tool sets count to 30 per section, where the REST API defaults to 10, and it returns highlights, the passages that address the query, instead of snippets (live tool schema, October 4, 2026). One keyless call with the count capped at 2 returned about 18,600 characters of tool-result text, so an uncapped call can fill a lot of context.

Set host-side controls in the config headers. The server documents X-Search-* headers that win over whatever the model sends, and fields such as country and include_domains can only be set this way (MCP server reference). A test against the keyless profile confirmed two of them: X-Search-Count: 2 returned two results when the request asked for ten, and X-Search-Include-Domains: you.com limited both results to you.com. An include list cannot be combined with an exclude or boost list, and each list is capped at 500 domains.

Scope the tools as well. Bare /mcp enables four by default: you-search, you-contents, you-balance, and you-discover. A coding agent that only searches and reads pages does not need the last two, and Cascade's 100-tool budget makes trimming worthwhile. Add ?tools=you-search,you-contents to the URL, as the examples above do, or send an X-Allowed-Tools header. you-research and you-finance live on their own paths, /mcp/research and /mcp/finance, which lets you give them separate keys and separate permission rules.

How do you confirm the agent is using the server?

A connected server with a tool list proves less than it seems. The live server answers a missing or empty Authorization header with a 401 and an OAuth challenge, even on initialize and tools/list. Any non-empty token gets a 200 on both, and a wrong key fails later, at the first search, as a 200 response whose result carries isError true and "Error code: 401". Probe with a real search outside Windsurf, so you can tell a missing key from a rejected one from a working one:

import json
import os
import urllib.error
import urllib.request

URL = "https://api.you.com/mcp?tools=you-search,you-contents"
body = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {"name": "you-search", "arguments": {"query": "windsurf mcp", "count": 1}},
}
request = urllib.request.Request(
    URL,
    data=json.dumps(body).encode(),
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ.get("YDC_API_KEY", ""),
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "User-Agent": "mcp-probe/1.0",
    },
)
try:
    reply = urllib.request.urlopen(request, timeout=30).read().decode()
except urllib.error.HTTPError as err:
    hint = ": the Authorization header is missing or empty" if err.code == 401 else ""
    raise SystemExit(f"HTTP {err.code}{hint}")
print("tool error: a key was sent but rejected" if '"isError":true' in reply else "search worked")

It prints HTTP 401 when the header is missing or empty, tool error when a key was sent but rejected, and search worked when the key is good. The probe spends one search call.

Then test in the editor with a question that cannot be answered from memory, such as a release note from this week. Built-in search is also available, so name the server in the prompt: use the youcom MCP server's you-search tool to find the latest release notes for the library I am using. The You.com Windsurf page gives the same advice when built-in tools win. For Devin Local, devin mcp list and devin mcp get youcom show what is configured (CLI docs). Ask the agent which tool it called, and check the call list rather than trusting a confident answer.

What fails, and how do you tell?

Symptom	Likely cause	Fix
The entry never appears	You edited the other agent's setup	Check the agent selector, then run devin mcp list for Devin Local or open the MCPs section in Cascade
401 on every call	An empty or missing Bearer token, for example an unset ${env:YDC_API_KEY} in Cascade	Export the variable in the environment Windsurf launches from, use ${file:...}, or switch to OAuth
Tools are listed but every search errors	A non-empty key the server rejects: it lists tools for any non-empty token and reports the 401 inside the search result	Run the probe above, then replace or rotate the key
Asked to sign in again in a new tool	Each MCP client keeps its own OAuth session	Run devin mcp login youcom for the Devin CLI as well
Tools missing in Cascade	The 100-tool limit across servers, or MCP is off for the team	Disable unused servers or tools, or ask an admin to enable MCP
Server blocked by policy	A team allowlist or registry that does not match the key name	Allowlist the exact key name, case-sensitive, or add the server to the team's MCP registry
The agent answers from memory or uses built-in search	Both search paths are available	Name the server in the prompt, or have an admin turn built-in web search off
Context fills after a few searches	count defaults to 30 per section	Set X-Search-Count in the headers
Page text is treated as instructions	Search results are untrusted text, and the agent can read files and run commands	Keep Devin Local's permission rules and sandbox on, and read our prompt injection guide

If you would rather call the API from your own code than hand the decision to an agent, our tool calling guide compares the two approaches, and the Web Search API guide covers the endpoint, pricing, and limits.

Related Guides

• How to Set Up the You.com MCP Server for Web Search in Any Client
• How to Add Web Search to Cursor With the You.com MCP Server
• How to Add Web Search to Claude Code: A Developer Installation Guide
• How to Give a Coding Agent Web Search With the You.com Web Search API
• What Is the You.com Web Search API? Endpoint, Pricing, and Limits