Skip to main content

Meta parameters for Databricks Vector Search MCP servers

Beta

This feature is in Beta.

When you build AI agents that use Databricks managed Vector Search MCP servers, use the _meta parameter to deterministically control tool behavior such as the maximum number of results to return and apply search filters.

The key benefit is that you can preset search behaviors (like result limits and filters) while keeping the actual search query flexible for your agent to generate dynamically.

The _meta parameter is part of the official MCP specification.

Tool call arguments vs. _meta parameters​

The Vector Search MCP server handles parameters in two ways:

  • Tool call arguments: Parameters that are typically dynamically generated by an LLM based on user input
  • _meta parameters: Configuration parameters that you can preset in your agent code to deterministically control search behavior

Supported _meta parameters​

The following _meta parameters are supported for Vector Search:

Parameter name

Type

Description

num_results

int

Number of results to return.

Default: 5

filters

str

JSON string containing filters to apply to the search. Must be a valid JSON string format.

Example: '{"updated_after": "2024-01-01"}'

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"

For detailed information about these parameters, see the Vector Search API documentation.

Example: Configure maximum results and filters for vector search retrieval​

This example shows how to use _meta parameters to control Vector Search behavior while allowing dynamic queries from your AI agent. It uses 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 ensure relevance
  • Use hybrid search for better accuracy than pure vector search

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/vector-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
                    }
                }
            )

            # 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())

Next steps​

Last updated on