Skip to main content
Last updated on

Web search on Databricks

This page describes how to ground responses with real-time information from the web on Databricks. Use the model-agnostic managed Model Context Protocol (MCP) Service system.ai.web_search with MCP-compatible clients and agents. Gemini and OpenAI foundation models also provide native web search through Foundation Model APIs.

prompt

Genie Code (Agent mode) can do this for you. Try this example prompt:

Query the databricks-gemini-3-1-pro model using the OpenAI client with the google_search parameter enabled, ask a question about a current event, and print the response.

Web search allows foundation models to retrieve up-to-date information from the internet during response generation. When web search is enabled, the model can search the web to find relevant information and incorporate it into its response. This is useful for questions about current events, recent data, or any topic where real-time information improves the response.

Use a managed MCP Service independently of your model provider, or enable native web search through a supported model API:

  • Managed MCP web search: Use the built-in system.ai.web_search MCP Service from an MCP-compatible client or agent. Databricks manages the backing model, so you don't choose a model for the service.
  • Gemini models: Use the google_search parameter with the Chat Completions API or the Google Gemini API.
  • OpenAI models: Use the web_search tool with the OpenAI Responses API.
  • Third-party MCP web search: Use a web search MCP server such as You.com from Databricks Marketplace as an alternative.
important

Native web search for OpenAI models is only available through the Responses API. It is not supported through the Chat Completions API.

Native web search through model APIs​

The following examples enable a model provider's native web search tool in a Foundation Model API request.

Gemini models with the Chat Completions API​

To enable web search for Gemini models using the Chat Completions API, pass google_search as a top-level parameter in the request body.

Python
import os
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('DATABRICKS_BASE_URL')

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=DATABRICKS_BASE_URL
)

response = client.chat.completions.create(
    model="databricks-gemini-3-1-pro",
    messages=[
        {"role": "user", "content": "What are the best Italian restaurants in San Francisco?"}
    ],
    extra_body={"google_search": {}}
)

print(response.choices[0].message.content)

Gemini models with the Google Gemini API​

To enable web search using the Google Gemini API, pass google_search as a tool.

Python
from google import genai
from google.genai import types
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = genai.Client(
    api_key="databricks",
    http_options=types.HttpOptions(
        base_url="https://example.staging.cloud.databricks.com/ai-gateway/gemini",
        headers={
            "Authorization": f"Bearer {DATABRICKS_TOKEN}",
        },
    ),
)

response = client.models.generate_content(
    model="databricks-gemini-3-1-pro",
    contents=[
        types.Content(
            role="user",
            parts=[types.Part(text="What are the best Italian restaurants in San Francisco?")],
        ),
    ],
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)

print(response.text)

OpenAI models with the Responses API​

To enable web search for OpenAI models, pass web_search as a tool using the OpenAI Responses API.

Python
import os
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('DATABRICKS_BASE_URL')

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=DATABRICKS_BASE_URL
)

response = client.responses.create(
    model="databricks-gpt-5",
    input=[
        {"role": "user", "content": "What are the best Italian restaurants in San Francisco?"}
    ],
    tools=[{"type": "web_search"}]
)

print(response.output_text)

Web search through MCP​

MCP-compatible clients and agents can call a web search tool independently of their model provider. Connect your client or agent to a web search MCP service or server using MCP.

Anthropic's native web search tool is not available through Databricks Foundation Model APIs. Use MCP to provide web search tools to agents that use Anthropic models.

Unity Gateway Beta

To use system.ai.dbsql, system.ai.sandbox, or system.ai.web_search, an account admin must enable the Unity Gateway beta from the account console Previews page. See Manage account previews.

Use the managed web search MCP Service​

The Databricks-provided MCP Service system.ai.web_search searches the public web without a Marketplace installation or a third-party API key. The service is model agnostic and works with MCP-compatible clients and agents, regardless of their model provider.

Databricks manages the model used by the service. You don't select or configure its backing model. Its web_search tool accepts only a natural-language query and returns a synthesized answer with citations.

Requirements​

Your workspace must meet the MCP Services requirements. The caller must have EXECUTE on the service, USE CATALOG on system, and USE SCHEMA on system.ai. Account users hold these privileges by default.

Connect a client​

The service URL is:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.web_search

For example, to connect the Claude Code client, install and configure the Unity Gateway CLI, then add the service and launch Claude Code:

Bash
ug mcp add --agents claude --names system.ai.web_search
ug claude

The Unity Gateway CLI authenticates through your Databricks CLI login and refreshes the token automatically. For other clients, see Other MCP clients.

For agent code, see Use MCP tools in a Python agent.

Set up the You.com MCP server​

You.com is a third-party alternative for MCP-compatible clients and agents.

  1. Navigate to Marketplace > Agents > MCP Servers in your Databricks workspace.
  2. Search for You.com and click Install.
  3. Configure the connection:
  • Connection name: Enter a name (for example, youcom_web_search).
  • Bearer token: Enter your You.com API key.
  1. Click Install.
  2. Grant USE CONNECTION privileges to appropriate users or groups under Catalog > Connections > [your connection] > Permissions.

After setup, the MCP server is available as a tool in AI Playground, agents, and other MCP-compatible clients. The proxy endpoint URL for your connection is:

https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>

Use You.com with Claude Code​

To use You.com with Claude Code and Databricks Foundation Model APIs, add the You.com MCP server:

Bash
claude mcp add youcom-search \
  --transport http \
  --url "https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>" \
  --header "Authorization: Bearer <your-databricks-pat>"

Verify the server was added with claude mcp list.

Alternatively, add the server directly to ~/.claude.json:

JSON
{
  "mcpServers": {
    "youcom-search": {
      "type": "http",
      "url": "https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>",
      "headers": {
        "Authorization": "Bearer <your-databricks-pat>"
      }
    }
  }
}

Supported models​

MCP web search requires a client or agent that can call MCP tools. It is not limited to a specific model provider. For agent integration, see Use MCP tools in a Python agent.

The following model requirements apply only to native web search through the Gemini and OpenAI APIs. Native web search is supported on all Gemini and OpenAI pay-per-token foundation models. See Detailed list of models supported by Databricks Foundation Model APIs for region availability.

Gemini models​

  • databricks-gemini-3-1-pro
  • databricks-gemini-3-1-flash-lite
  • databricks-gemini-3-flash

OpenAI models​

  • databricks-gpt-5-5-pro
  • databricks-gpt-5-5
  • databricks-gpt-5-4
  • databricks-gpt-5-4-mini
  • databricks-gpt-5-4-nano
  • databricks-gpt-5-3-codex
  • databricks-gpt-5-2
  • databricks-gpt-5-1
  • databricks-gpt-5
  • databricks-gpt-5-mini
  • databricks-gpt-5-nano

Data privacy and retention​

When you enable web search through Databricks Foundation Model APIs, the search runs on a Databricks-hosted foundation model endpoint. The search query and results are processed by the hosted model regardless of which model your application calls. The same data-protection and retention terms that govern Model Serving apply to these requests:

  • Databricks does not use inputs sent to Model Serving, or outputs from it, to train models. See Model Serving data protection.
  • Any temporary storage for abuse detection is kept in the same region as your workspace and is time-bounded. See Data retention.

The model formulates search queries from your prompt and sends them to an external search provider to retrieve results. Treat prompt content that reaches web search as data that leaves Databricks for the search provider, and scope what your application sends accordingly.

Limitations​

  • Web search is not available for workspaces with HIPAA/BAA compliance enabled because web search queries are sent to external search services that are not HIPAA-compliant.
  • Web search results depend on the model's ability to formulate search queries and synthesize results. Response quality may vary.
  • Native web search through the Gemini and OpenAI APIs is only available on pay-per-token foundation model endpoints. This restriction does not apply to the model that calls a web search tool through MCP.
  • The built-in system.ai.web_search MCP Service is available in supported US regions or in workspaces that allow cross-Geo processing. See Databricks-provided MCP Services for availability and limitations.
  • The built-in MCP Service is not available when workspace network controls disable internet access.
  • Native web search for OpenAI models is only available through the Responses API. The Chat Completions API does not support native web search for OpenAI models.
  • Native web search for Gemini models is not available when cross-region processing is disabled. Gemini does not support in-geo search processing, so any workspace with data residency enforcement is ineligible.
  • Native web search for OpenAI models is not available when cross-region processing is disabled, unless the workspace is in an eligible geo (Americas or Europe). OpenAI supports in-geo search processing in these regions.

Additional resources​

On this page