What Is MCP Web Search? Live Results for Model Context Protocol Agents

TLDR: MCP web search is live web search exposed as a tool through the Model Context Protocol, so any MCP client can discover and call it without custom integration code. The client lists the server's tools, the model picks one, and the client sends a tools/call request and returns the result to the model. The current protocol revision, 2026-07-28, removed the initialize handshake. This guide covers how a call travels, how servers differ, and when a direct API fits better.

A model answers from training data, so an agent that needs this week's facts needs a retrieval tool. MCP standardizes how that tool is described and called, which turns "add web search" into a configuration entry. The entry hides decisions about which server, which transport, what the model may set, and what happens to the results. For the protocol itself, read our Model Context Protocol guide. To register the You.com server in a client, use the setup guide, which this page does not repeat.

What Is MCP Web Search?

MCP web search is web search delivered as a tool over the Model Context Protocol. The MCP documentation calls the protocol an open-source standard for connecting AI applications to external systems, with search engines among the tools they can reach. Three participants are involved. The host is the AI application, such as Claude Code or Visual Studio Code. It creates one client per server, and each client keeps a dedicated connection. The server provides the tools, running on your machine over STDIO or remotely over Streamable HTTP, per the architecture overview.

A search server exposes one or more tools, and the model decides when to call them. The tools specification calls tools model-controlled and says there should always be a human in the loop who can deny an invocation. That is a recommendation for hosts, so check what yours does.

MCP does not do the searching. It defines how a tool is described, called, and answered. Result quality, freshness, and page extraction come from the index and crawler behind the server, so two servers that look identical in a config can behave differently on your queries.

What Does an MCP Web Search Tool Look Like?

A client discovers tools with tools/list. Each definition carries a name, a description, and an input schema, plus an optional title, output schema, and annotations. Hosts typically pass the name, description, and input schema to the model, so they work as part of your prompt. We listed the keyless You.com free profile on October 12, 2026. It returned two tools, you-search and you-discover, and the table summarizes you-search.

Field	What you-search carries	Why it matters
Name and title	you-search and "Web Search"	The specification says to treat names as case-sensitive, so copy them from tools/list.
Description	Best uses, one intent per search, a note that snippets are not page content and should be read with you-contents, and advice to widen the query on zero results	It is written for the model. A vague one produces vague queries.
Input schema	query (required, up to 50 words or 400 characters), count (1 to 100), freshness, offset (0 to 9), extraction (none, highlights, or full_page), exclude_domains (up to 500), and more	Each parameter is another decision for the model on every call.
Output schema	results.web entries with url, title, description, snippets, page_age, and contents, plus results.news	A client can validate results instead of guessing.
Annotations	readOnlyHint true, destructiveHint false, openWorldHint true	They are hints. Clients must treat them as untrusted unless the server is trusted.

One design choice is worth looking for in any server: settings reserved for the host. Under the reserved _meta key com.you.com/search, the host can set language, country, include_domains, and boost_domains on each call. Per the MCP Server documentation, those values win over anything the model supplies and are never exposed to it. If your product must keep the model inside approved domains, a server that lets the host pin that setting is safer than one that asks the model to follow a rule.

How Does a Search Call Travel Over MCP?

A call moves through tools/list, the model's choice of tool and arguments, tools/call, the server's result, and the host passing that result back to the model. What changed recently is the connection before those steps. The current revision, 2026-07-28, made MCP stateless. According to its changelog, the initialize handshake and protocol-level sessions are gone, and every request carries its protocol version and client capabilities in _meta. Servers must implement a new server/discover request for supported versions, capabilities, and identity. Tutorials written for earlier revisions describe a handshake that a client talking to a 2026-07-28 server no longer performs.

Behavior	Through 2025-11-25	2026-07-28
Connection setup	The client sends initialize, then notifications/initialized	No handshake; each request stands alone
Protocol version	Agreed once, during initialization	Declared on every request in _meta and mirrored in the MCP-Protocol-Version HTTP header
Sessions	A server could assign an Mcp-Session-Id	Removed; a server that needs state returns an explicit handle that the model passes as a tool argument
Discovery	Capabilities came back in the initialize response	server/discover, which servers must implement and clients may call
Log messages	The client could set a session-wide level with logging/setLevel	The request sets a level in _meta, and servers must not send log notifications for requests that did not ask

Real servers sit between the two eras, so test the one you will use. On October 12, 2026, we probed the keyless You.com free profile. A server/discover request returned supportedVersions of ["2026-07-28"], and a legacy initialize request proposing 2025-06-18 was still accepted. A tools/call with the 2026-07-28 headers and metadata came back as one application/json object with resultType complete. The same call without the version headers or metadata came back as a text/event-stream whose first event was an id-less notifications/message log line, followed by the result. That is one probe, not a contract: tools/list and server/discover are the source of truth.

Two client rules follow. Support both response types, because the Streamable HTTP specification requires clients to handle application/json and text/event-stream. And match the reply by JSON-RPC id instead of taking the first event, because a stream can carry notifications ahead of the result. This is the tools/call from our probe, trimmed to one result.

POST /mcp?profile=free HTTP/1.1
Host: api.you.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: you-search

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "you-search",
    "arguments": {"query": "model context protocol specification", "count": 2},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "search-demo", "version": "0.1"},
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "structuredContent": {
      "results": {"web": [{
        "url": "https://github.com/modelcontextprotocol",
        "title": "Model Context Protocol · GitHub",
        "page_age": "2026-03-14T00:00:00",
        "contents": {"highlights": ["..."]}
      }]},
      "metadata": {"query": "model context protocol specification"}
    },
    "content": [{"type": "text", "text": "{\"results\": ...}"}],
    "_meta": {"you/usage": {"sku": "search", "results_returned": 2, "extraction_mode": "highlights"}}
  }
}

The text block repeats structuredContent as a JSON string, for clients that predate structured results. The you/usage entry is You.com's own addition and gives a client a number to log for cost tracking.

How Do You Call an MCP Search Tool From Code?

A host or SDK usually does this for you, but every failure you debug shows up at this layer. The function below sends tools/list and a you-search tools/call to the free profile using only the Python standard library. It sends the 2026-07-28 headers and metadata, accepts either response type, matches the reply by id, and reads structuredContent, falling back to the JSON string in the text block.

import json
import urllib.error
import urllib.request

MCP_URL = "https://api.you.com/mcp?profile=free"  # keyless: you-search and you-discover, 100 queries per day
PROTOCOL = "2026-07-28"


def mcp_request(method, params, rpc_id, tool=None, url=None):
    """POST one JSON-RPC request and return the result of the reply whose id matches."""
    params = dict(params)
    params["_meta"] = {
        "io.modelcontextprotocol/protocolVersion": PROTOCOL,
        "io.modelcontextprotocol/clientInfo": {"name": "search-demo", "version": "0.1"},
        "io.modelcontextprotocol/clientCapabilities": {},
    }
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "MCP-Protocol-Version": PROTOCOL,
        "Mcp-Method": method,
        "User-Agent": "search-demo/0.1",  # the default Python User-Agent gets HTTP 403 from api.you.com
    }
    if tool:
        headers["Mcp-Name"] = tool
    body = json.dumps({"jsonrpc": "2.0", "id": rpc_id, "method": method, "params": params})
    req = urllib.request.Request(url or MCP_URL, data=body.encode(), headers=headers, method="POST")
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            content_type = resp.headers.get("Content-Type", "")
            raw = resp.read().decode("utf-8")
    except urllib.error.HTTPError as err:
        # An unsupported protocol version is an HTTP 400 whose body lists the versions the server speaks.
        raise RuntimeError("HTTP %d: %s" % (err.code, err.read().decode("utf-8", "replace")[:300])) from err
    return parse_reply(raw, content_type, rpc_id)


def parse_reply(raw, content_type, rpc_id):
    if content_type.startswith("application/json"):
        messages = [json.loads(raw)]
    else:  # text/event-stream: one JSON message per event, possibly split across data: lines
        messages = []
        for event in raw.replace("\r\n", "\n").split("\n\n"):
            data = [ln[5:].lstrip() for ln in event.splitlines() if ln.startswith("data:")]
            if data:
                messages.append(json.loads("\n".join(data)))
    for message in messages:
        if message.get("id") == rpc_id:  # skips id-less notifications such as notifications/message
            if "error" in message:
                raise RuntimeError("JSON-RPC error: " + json.dumps(message["error"]))
            return message["result"]
    raise RuntimeError("no reply with id %r in the response" % rpc_id)


def web_search(query, count=5):
    result = mcp_request(
        "tools/call",
        {"name": "you-search", "arguments": {"query": query, "count": count}},
        rpc_id=2,
        tool="you-search",
    )
    if result.get("isError"):  # the tool ran and failed; the text is written for the model
        raise RuntimeError(result["content"][0]["text"])
    payload = result.get("structuredContent") or json.loads(result["content"][0]["text"])
    return payload.get("results", {}).get("web", [])


if __name__ == "__main__":
    tools = mcp_request("tools/list", {}, rpc_id=1)["tools"]
    print("tools:", [t["name"] for t in tools])
    for hit in web_search("model context protocol specification", count=3):
        print(hit["url"], "|", hit.get("title"))

The User-Agent line matters. On October 12, 2026, a request with Python's default urllib User-Agent was refused by api.you.com with HTTP 403 and Cloudflare error 1010, and the same request with a custom User-Agent succeeded. Requests sent with the default User-Agent strings of the requests and httpx libraries were not refused in our check, so the problem is specific to urllib's default.

MCP has two error channels, and the free profile showed both on October 12, 2026. An unknown tool name, you_search, came back as a JSON-RPC error with code -32602, which the function raises. A count of 1000 came back as a normal result with isError set to true and a message for the model saying count must be 100 or less, so the function checks that flag separately. The specification says clients should pass those messages to the model so it can correct itself. The HTTP layer can also fail first: a server that does not support the requested protocol version answers HTTP 400 with a JSON-RPC error body, code -32022, that lists the versions it does support, so log the body, not only the status.

We compiled this code, ran it against a local mock server that replays each response shape and error path, and ran it once against the free profile. The mock confirms the parsing, not tomorrow's server behavior, which is why the checklist below includes a known-answer query.

Which MCP Servers Offer Web Search?

Several search vendors host or publish MCP servers. The table summarizes each vendor's own documentation as of October 2026. Tool counts are not a quality measure, and free paths change, so read the linked page before you build on a row.

Server	Where it runs	Authentication	Documented search tools
You.com	Remote at api.you.com/mcp, or local with npx @youdotcom-oss/mcp over STDIO	Free profile with no key, an API key as a bearer token, or OAuth 2.1	Six tools in all: you-search, you-contents, you-research, you-finance, you-balance, you-discover. Bare /mcp lists four by default, and the free profile lists two.
Tavily	Remote at mcp.tavily.com/mcp, or local with npx tavily-mcp	Keyless with rate limits via an X-Tavily-Access-Mode header, OAuth, or an API key in the URL or an Authorization header	The MCP page names tavily-search and tavily-extract
Exa	Remote at mcp.exa.ai/mcp, or local with npx exa-mcp-server	Keyless with rate limits, OAuth, or an API key in the x-api-key header	web_search_exa and web_fetch_exa by default, web_search_advanced_exa on request, agent_run with OAuth or a key
Brave	Local process from the brave/brave-search-mcp-server repository, STDIO by default and HTTP optional	Brave Search API key	brave_web_search, plus local, place, image, video, and news search, LLM context, and summarization

Four things decide the choice: where the server runs (a process you operate or a vendor's uptime), how it authenticates (a config file, a header, or an OAuth grant), how much tool surface the model gets and whether you can scope it down, and result quality on your own queries. For side-by-side installs, see our guides to Tavily MCP and Exa MCP.

Should You Use an MCP Server, a Search API, or a Built-In Search Tool?

Situation	Better fit	Why
An agent should decide when and what to search, inside a host that already speaks MCP	MCP server	The host handles discovery, approval, and calling, so you write no integration code
Your application needs the JSON, for example to rerank, cache, or cite results in a fixed pipeline	Search API or SDK called from your code	Your code, not the model, decides when to search and what reaches the prompt. The You.com docs recommend their Python SDK when you want a typed client that tracks new API fields
The host ships its own search and you want a different provider	MCP server, with the built-in search turned off	Two search tools in one host can conflict. The You.com notes for Cursor say to turn off Cursor's built-in web search, and our Cursor guide describes the symptom

The You.com docs draw the same line for TypeScript: use the REST APIs when the application needs the JSON, and use the MCP server when an agent should call the tools. The tradeoff underneath is control. With an MCP tool, the model decides how many searches to run and what each query says, so call volume, token use, and cost vary with the task. With a direct API call, your code fixes the count, the parameters, and what reaches the model. Agents that explore suit model-controlled search, and pipelines that must behave the same way every run suit a fixed call. Our guides to what a web search API is and choosing a web search API for agents cover the direct route.

What Risks Does a Search Tool Add?

A search tool reads from the open web and sends text out to it, which creates two risks. The first is untrusted input: a retrieved page can contain instructions aimed at the model, and the model may follow them as if the user had written them. The specification's client guidance recommends validating tool results before they reach the model, and our article on prompt injection and intent hijacking shows how a search result becomes a command. The second is data leaving your boundary: the model writes the query and may include text from the conversation. The specification recommends that clients show tool inputs to the user before calling the server, to avoid accidental or malicious exfiltration.

Two smaller controls follow. Keep credentials out of shared files: Tavily's documentation shows an API key in the URL query string, which can end up in config files and logs, so prefer OAuth or a header where your client supports it. And watch volume: the full_page extraction mode returns whole pages instead of passages, which enlarges every response, and the you-search schema notes that its fetch source bills at live-crawl rates.

What Should You Test Before You Rely on It?

1. Run one query whose correct top result you know, through the client your users will use, and confirm the URL appears. A listing proves the connection. A real call proves the query path. Our setup guide covers verification and failure modes.
2. Force both error channels: call an unknown tool, then send an out-of-range argument, and confirm your code tells a JSON-RPC error from a result with isError set to true.
3. Feed your parser a recorded JSON reply and a recorded event stream with a notification ahead of the result.
4. Send a nonsense query and read what the agent tells the user. The you-search description tells the model to widen the query on zero results, so confirm your agent does not invent an answer instead.
5. Check what the user sees before a call runs, and test the denial path.
6. Decide what the agent does when the tool fails at a cap, such as 100 queries per day on the free profile. It should stop and say so, not answer from memory.

Related Guides

• What Is Model Context Protocol (MCP)?
• How to Set Up the You.com MCP Server for Web Search in Any Client
• Tavily MCP vs You.com MCP
• Exa MCP Server vs You.com
• Prompt Injection and Intent Hijacking in AI Agents