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

TLDR: To add web search to OpenCode, put a remote entry for the You.com MCP server under the mcp key in opencode.json. Use https://api.you.com/mcp with your key in an environment variable, or https://api.you.com/mcp?profile=free for 100 keyless queries a day. OpenCode also ships a built-in websearch tool, but it runs only on OpenCode's own providers or with an environment flag.

OpenCode is an open source coding agent that runs in a terminal, as a desktop app, or as an IDE extension, and its documentation says it supports both local and remote MCP servers. The real setup questions are which search backend sits behind the agent, where the API key lives, and how you tell when something has broken. This guide was checked against OpenCode's docs, its published config schema, and the live You.com MCP server on October 3, 2026.

What web search does OpenCode already have?

OpenCode's tools page lists two web tools. webfetch reads a page when the model already has its URL. websearch finds pages. It uses Exa or Parallel as its backend, needs no API key, and is available only when you run the OpenCode or OpenCode Go provider, or when you launch with OPENCODE_ENABLE_EXA or OPENCODE_ENABLE_PARALLEL set to a truthy value such as 1. Both tools have matching keys in OpenCode's permission config, so you can allow, ask, or deny each one.

So OpenCode does have web search, and the real limits are narrower. With another model provider, the built-in search stays off until you set a flag, and you do not choose the index behind it. An MCP server adds a separate tool whose backend you pick. If the built-in tool already answers your questions, you do not need another one. The case for adding You.com rests on three specifics:

• Host-side search controls. The host application can set country, language, include domains, and boost domains out of band. The model never sees those settings and cannot override them, per the MCP server reference.
• Search and page reading from one server. With a key, the default endpoint also exposes you-contents for page extraction, and the research and finance tools sit on their own paths.
• One server across agents. The same URL works in Cursor, Claude Code, and OpenClaw, so a team can standardize on one search layer. The client-neutral version of this setup is in the any-client MCP guide.

Which You.com setup fits OpenCode?

There are five ways to connect, and they differ mainly in how sign-in works and which tools appear. The table follows the You.com OpenCode page and the MCP server reference, as checked in October 2026.

Setup	What you change	Sign-in	Tools you get
Plugin	Run opencode plugin @youdotcom-oss/opencode	OAuth on the first call for the you, you-research, and you-finance servers; none for you-free and you-docs	Four skills and five MCP servers
Remote, keyless	Add an mcp entry with ?profile=free	None	you-search and you-discover, 100 queries a day
Remote, API key	Add an mcp entry with an Authorization header	Bearer key	you-search, you-contents, you-balance, and you-discover
Remote, OAuth	Add an mcp entry with no headers, then run opencode mcp auth you-com	OAuth 2.1	The same four tools as the keyed setup
Local package	Set type to local and run npx -y @youdotcom-oss/mcp	YDC_API_KEY, or YDC_PROFILE=free	The tools in your YDC_ALLOWED_TOOLS allowlist

Use the keyless profile to prove the wiring, a key or OAuth for daily work, and the plugin if you also want its four skills, which tell the model when to use each tool and how to cite what it finds. The rest of this guide uses the remote entry, because it is the one path with nothing to install.

How do you add the You.com MCP server to opencode.json?

Edit ~/.config/opencode/opencode.json for search in every project, or the opencode.json in a repository root for one project. OpenCode merges config files instead of replacing them, and project values win on conflicting keys, so a stale you-com entry in a repo can override the one in your home directory. The keyless version needs no secrets:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "you-com": {
      "type": "remote",
      "url": "https://api.you.com/mcp?profile=free"
    }
  }
}

That profile exposes you-search and you-discover only, at 100 queries a day. When you are ready for a key, replace the block with this:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "you-com": {
      "type": "remote",
      "url": "https://api.you.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:YDC_API_KEY}"
      }
    }
  }
}

Three details in that block matter. OpenCode substitutes {env:YDC_API_KEY} from the environment, so the key never sits in a file you might commit, and it also supports {file:path} for secrets kept in a separate file. If the variable is not set, OpenCode replaces it with an empty string, which the failure table below shows turns into a 401. And "oauth": false is the setting OpenCode's MCP docs give for servers that use API keys, because OpenCode otherwise treats a 401 response as the start of an OAuth flow.

If you prefer prompts to hand-editing, opencode mcp add walks you through adding a local or remote server. The plugin route is one command, opencode plugin @youdotcom-oss/opencode, and the --global flag installs it in your global config.

How do you confirm OpenCode is calling You.com?

1. Export the key in the shell that launches OpenCode, then start OpenCode. In a second terminal, run opencode mcp list to see every configured server and its connection status.
2. If you-com is not connected, run opencode mcp debug you-com. OpenCode's docs say it reports the auth status, tests HTTP connectivity, and attempts the OAuth discovery flow.
3. Ask something training data cannot answer, such as what changed in a library release this month, and read the transcript, not just the answer. OpenCode prefixes each MCP tool with the server name, so a working setup shows a call to you-com_you-search followed by results with URLs.
4. If there is no tool call, the model chose not to search. The next section covers how to steer it.

To separate key problems from config problems, call the server directly, outside OpenCode. With a valid key the response lists the default tools. A missing or empty key returns the 401 described in the failure table below.

curl -sS https://api.you.com/mcp \
  -H "Authorization: Bearer $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

How do you make the agent use You.com instead of the built-in tool?

When two search tools are available, the model picks one. OpenCode's own MCP examples use the simplest fix: tell the agent which tool to use, either in the prompt or in an AGENTS.md file. OpenCode reads AGENTS.md from the project root, and from ~/.config/opencode/AGENTS.md for every session. A rule this short is enough:

When you need current information from the web, call the you-com_you-search tool.
Prefer official documentation and release notes over blog posts.
If a search returns nothing useful, reformulate once. Do not repeat the same query.

Permissions are the stricter lever:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "you-com_*": "ask",
    "websearch": "deny"
  }
}

The you-com_* wildcard is the documented way to require approval for every tool from one MCP server, which suits the first week, when you want to read each query before it runs. Denying websearch removes any ambiguity if you enabled the built-in tool with an environment flag. OpenCode also has a doom_loop permission that fires when the same tool call repeats three times with identical input. It defaults to ask, so an agent stuck on one query stops at an approval prompt instead of repeating it.

How do you control result size and sources?

The tool listing the server returned on October 3, 2026 defaults count, the maximum number of results per section, to 30, and OpenCode's docs warn that every MCP server adds to the context. You can cap the count from the host side, where the model cannot raise it. The You.com MCP reference lists an X-Search-* header for each override, and OpenCode sends the headers object with each request:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "you-com": {
      "type": "remote",
      "url": "https://api.you.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:YDC_API_KEY}",
        "X-Search-Count": "8"
      }
    }
  }
}

We checked two of these headers against the keyless profile on October 3, 2026. A query that returned 19 results by default returned exactly 3 with X-Search-Count: 3. And X-Search-Include-Domains: opencode.ai,github.com, with a count of 6, returned six results, all from those two hosts, which is the pattern for an agent that should read only trusted documentation. Include domains cannot be combined with exclude or boost domains. Our site restriction guide covers the same idea for the API.

A count cap limits how many results come back, not necessarily how many characters. In that test, three results still produced about 33,000 characters of output, against about 39,000 for nineteen, because each of the three carried far longer highlights. Measure one real tool result in your transcript before you assume a cap saves context.

What goes wrong, and how do you detect it?

Most failures show up as a quiet absence: no tool call, no tools, or an authentication prompt that does not match what you configured. The table pairs each symptom with what we reproduced or what the docs state.

Symptom	Cause	Fix
OpenCode asks you to authenticate even though you set a key	{env:YDC_API_KEY} expanded to an empty string. The server answers 401 with "Invalid Bearer token format" and an OAuth challenge, and OpenCode treats a 401 as the start of its OAuth flow.	Export the variable in the shell that starts OpenCode, restart, and set "oauth": false.
The server connects but no you-com_ tools appear	The profile and the path exclude every tool. https://api.you.com/mcp/research?profile=free returns a 200 with an empty tool list.	Remove ?profile=free from research and finance paths, or use /mcp.
you-search works but you-contents is missing	The keyless profile exposes only you-search and you-discover.	Switch to a key or OAuth on /mcp.
Tools never load on a slow connection	Fetching the tool list exceeded the server's timeout.	Raise the server's timeout option, which OpenCode takes in milliseconds.
Config changes have no effect	Invalid JSON. The You.com OpenCode page says OpenCode silently skips invalid MCP entries.	Validate the file and keep the $schema line so your editor flags bad keys.
The agent keeps using the other search tool	Both tools are available and the instructions name neither.	Name the tool in AGENTS.md or deny websearch.
A key appears in git history	A literal key in a project opencode.json.	Rotate the key and switch to {env:YDC_API_KEY}.

Two habits catch most of these. Run opencode mcp list after every config change, and keep one canary prompt about something recent so you notice when search quietly stops working.

What does search cost in a coding agent?

The keyless profile is free for 100 queries a day. Beyond that, the You.com billing page prices the Web Search API at $5.00 per 1,000 calls and the Contents API at $1.00 per 1,000 pages, as of October 2026. An agent that runs 30 searches on each of 22 working days makes 660 calls, which is $3.30 a month at that rate. Full-page extraction adds $1.00 per 1,000 pages crawled live, and pages served from cache are free under the default source. Limits, errors, and the rest of the pricing detail are in the Web Search API reference. The default endpoint also exposes you-balance, so you can check the account balance from inside a session.

What should you check before rolling it out to a team?

Search results are untrusted text placed in the model's context, so prompt injection applies here as it does to any agent with a search tool. Our guide to prompt injection and intent hijacking covers the threat model, and the ask permission above gives you a human checkpoint while you learn what the agent searches for.

Organizations can also ship MCP servers through OpenCode's remote config, disabled by default. A developer then enables one by adding it to the local config with enabled: true, and local values override the remote defaults, per OpenCode's docs.

Before you standardize, run the same five version-sensitive prompts through the built-in tool and through You.com, and compare which sources each cites and how many tool calls each needs. Do it on your own repositories. If you would rather call the API from your own tool-calling code than run an MCP server, this coding-agent guide covers that route.

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 OpenClaw 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