AI Search

Preview

The AI Search MCP server is a Databricks managed MCP server that lets agents run semantic search over your AI Search indexes to find relevant documents, with results governed by Unity Catalog permissions. Querying an index requires Databricks managed embeddings.

URL pattern	OAuth scope
`https://<workspace-hostname>/api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name}`	`ai-search`

note

AI Search was formerly Vector Search. The previous /api/2.0/mcp/vector-search/ URL prefix and vector-search scope still work.

AI Search `_meta` parameters

AI Search supports the following _meta parameters:

Parameter name	Type	Description
`columns`	`str`	Comma-separated list of column names to return in the search results. Example: `"id,text,metadata"` If not specified, all columns (except internal columns starting with "__") are returned.
`columns_to_rerank`	`str`	Comma-separated list of column names whose content the reranking model uses for re-scoring. The reranker uses this content to re-score all search results to improve relevance. Example: `"text,title,description"` If not specified, reranking is not performed.
`filters`	`str`	JSON string containing filters to apply to the search. Must be valid JSON. Example: `'{"updated_after": "2024-01-01"}'` If not specified, no filters are applied.
`include_score`	`bool`	Whether to include the similarity score in the returned results. Supported values: `"true"` or `"false"` Default: `"false"`
`num_results`	`int`	Number of results to return. Example: `"5"`
`query_type`	`str`	Search algorithm to use for retrieving results. Supported values: `"ANN"` (approximate nearest neighbor, default) or `"HYBRID"` (combines vector and keyword search) Default: `"ANN"`
`score_threshold`	`float`	Minimum similarity score threshold for filtering results. Results with scores below this threshold are excluded. Example: `"0.7"` If not specified, no score filtering is applied.

Parameter name	Type	Description
`columns`	`str`	Comma-separated list of column names to return in the search results. Example: `"id,text,metadata"` If not specified, all columns (except internal columns starting with "__") are returned.
`columns_to_rerank`	`str`	Comma-separated list of column names whose content the reranking model uses for re-scoring. The reranker uses this content to re-score all search results to improve relevance. Example: `"text,title,description"` If not specified, reranking is not performed.
`filters`	`str`	JSON string containing filters to apply to the search. Must be valid JSON. Example: `'{"updated_after": "2024-01-01"}'` If not specified, no filters are applied.
`include_score`	`bool`	Whether to include the similarity score in the returned results. Supported values: `"true"` or `"false"` Default: `"false"`
`num_results`	`int`	Number of results to return. Example: `"5"`
`query_type`	`str`	Search algorithm to use for retrieving results. Supported values: `"ANN"` (approximate nearest neighbor, default) or `"HYBRID"` (combines vector and keyword search) Default: `"ANN"`
`score_threshold`	`float`	Minimum similarity score threshold for filtering results. Results with scores below this threshold are excluded. Example: `"0.7"` If not specified, no score filtering is applied.

For detailed information about these parameters, see the AI Search Python SDK documentation.

Example: configure maximum results and filters for AI Search retrieval

This example shows how to use _meta parameters to configure AI Search behavior while allowing dynamic queries from your agent using the official Python MCP SDK.

In this scenario, you want to:

Always limit search results to exactly 3 items for consistent response times
Only search recent documentation (updated after 2024-01-01) to verify relevance
Use hybrid search for better accuracy than pure vector search
Return only specific columns (id, text, and metadata)
Include similarity scores in the results
Exclude results with similarity scores below 0.5
Use reranking on text and title columns to improve relevance

To run this example, set up your Python environment for managed MCP development:

Python
# Import required libraries for MCP client and Databricks authentication
import asyncio
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult

async def run_vector_search_tool_call_with_meta():
    # Initialize Databricks workspace client for authentication
    workspace_client = WorkspaceClient()

    # Construct the MCP server URL for your specific catalog and schema
    # Replace <workspace-hostname>, YOUR_CATALOG, and YOUR_SCHEMA with your values
    mcp_server_url = "https://<workspace-hostname>/api/2.0/mcp/ai-search/YOUR_CATALOG/YOUR_SCHEMA"

    # Establish connection to the MCP server with OAuth authentication
    async with streamablehttp_client(
        url=mcp_server_url,
        auth=DatabricksOAuthClientProvider(workspace_client),
    ) as (read_stream, write_stream, _):

        # Create an MCP session for making tool calls
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the session before making requests
            await session.initialize()

            # Create the tool call request with both dynamic and preset parameters
            request = CallToolRequest(
                method="tools/call",
                params={
                    # Tool name follows the pattern: CATALOG__SCHEMA__INDEX_NAME
                    "name": "YOUR_CATALOG__YOUR_SCHEMA__YOUR_INDEX_NAME",

                    # Dynamic arguments - typically provided by your AI agent or user input
                    "arguments": {
                        "query": "How do I reset my password?"  # This comes from your agent
                    },

                    # Meta parameters - preset configuration to control search behavior
                    "_meta": {
                        "num_results": "3",  # Limit to 3 results for consistent performance
                        "filters": '{"updated_after": "2024-01-01"}',  # JSON string for date filtering
                        "query_type": "HYBRID",  # Use hybrid search for better relevance
                        "columns": "id,text,metadata",  # Return only specific columns
                        "score_threshold": "0.5",  # Filter out results with similarity score < 0.5
                        "include_score": "true",  # Include similarity scores in results
                        "columns_to_rerank": "text,title"  # Use reranker on these columns for better quality
                    }
                }
            )

            # Send the request and get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_vector_search_tool_call_with_meta())

AI Search _meta parameters​

Example: configure maximum results and filters for AI Search retrieval​

AI Search `_meta` parameters

Example: configure maximum results and filters for AI Search retrieval