Metaparâmetros para Databricks gerenciar servidores MCP

info

Visualização

Este recurso está em Pré-visualização Pública.

Ao criar agentes AI que usam servidores Databricks gerenciando MCP, use o parâmetro _meta para controlar o comportamento da ferramenta, como limites de resultados, filtros de pesquisa ou seleção SQL warehouse . Isso permite que você predefina configurações predefinidas, mantendo as consultas flexíveis para que seu agente as gere dinamicamente.

O parâmetro _meta faz parte da especificação oficial do MCP.

Argumentos de chamada de ferramenta vs. parâmetros `_meta`

Os servidores Databricks gerenciam MCP e lidam com parâmetros de duas maneiras:

Argumentos de chamada da ferramenta : Parâmetros que um LLM normalmente gera dinamicamente com base na entrada do usuário.
Parâmetros_meta : Parâmetros de configuração que você pode predefinir no código do seu agente para controlar o comportamento de forma determinística.

Parâmetros do servidor DBSQL MCP `_meta`

Os seguintes parâmetros _meta são suportados para o servidor DBSQL MCP:

Nome do parâmetro	Tipo	Descrição
`warehouse_id`	`str`	O ID do SQL warehouse a ser usado para executar as consultas. Exemplo: `"a1b2c3d4e5f67890"` Caso não seja especificado, o sistema seleciona automaticamente um armazém com base nos recursos e permissões.

Nome do parâmetro

Tipo

Descrição

warehouse_id

str

O ID do SQL warehouse a ser usado para executar as consultas.

Exemplo: "a1b2c3d4e5f67890"

Caso não seja especificado, o sistema seleciona automaticamente um armazém com base nos recursos e permissões.

Exemplo: Especifique um SQL warehouse para consultas DBSQL.

Este exemplo mostra como usar o parâmetro warehouse_id _meta para especificar qual SQL warehouse deve executar consultas do servidor DBSQL MCP usando o SDKoficialPython MCP.

Neste cenário, você quer:

Utilize um SQL warehouse específico para a execução de consultas em vez de deixar o sistema selecionar um automaticamente.
Garanta um desempenho consistente encaminhando as consultas para um armazém dedicado.

Para executar este exemplo, configure seu ambiente Python para gerenciar o desenvolvimento do MCP:

Expanda para ver o exemplo de código.

Para encontrar o ID do seu SQL warehouse , consulte Conectar-se a um SQL warehouse.

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_dbsql_tool_call_with_meta():
    # Initialize Databricks workspace client for authentication
    workspace_client = WorkspaceClient()

    # Construct the MCP server URL for DBSQL
    # Replace <workspace-hostname> with your workspace hostname
    mcp_server_url = "https://<workspace-hostname>/api/2.0/mcp/sql"

    # 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 warehouse_id in _meta
            request = CallToolRequest(
                method="tools/call",
                params={
                    # Tool name for executing SQL queries
                    "name": "execute_sql",

                    # Dynamic arguments - typically provided by your AI agent
                    "arguments": {
                        "query": "SELECT * FROM my_catalog.my_schema.my_table LIMIT 10"
                    },

                    # Meta parameters - specify which warehouse to use
                    "_meta": {
                        "warehouse_id": "a1b2c3d4e5f67890"  # Your SQL warehouse ID
                    }
                }
            )

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

Parâmetros do servidor MCP de busca vetorial `_meta`

Os seguintes parâmetros _meta são suportados para Pesquisa de Vetores:

Nome do parâmetro	Tipo	Descrição
`columns`	`str`	Lista de nomes de colunas, separados por vírgula, a serem retornados nos resultados da pesquisa. Exemplo: `"id,text,metadata"` Caso não seja especificado, todas as colunas (exceto as colunas internas que começam com "__") serão retornadas.
`columns_to_rerank`	`str`	Lista de nomes de colunas, separados por vírgulas, cujo conteúdo o modelo de reclassificação utiliza para reavaliar a pontuação. O mecanismo de reclassificação usa esse conteúdo para reavaliar todos os resultados da pesquisa, a fim de melhorar a relevância. Exemplo: `"text,title,description"` Caso não seja especificado, a reclassificação não será realizada.
`filters`	`str`	Cadeias JSON contendo filtros a serem aplicados à pesquisa. Deve ser um JSON válido. Exemplo: `'{"updated_after": "2024-01-01"}'` Caso não seja especificado, nenhum filtro será aplicado.
`include_score`	`bool`	Indica se a pontuação de similaridade deve ser incluída nos resultados retornados. Valores suportados: `"true"` ou `"false"` padrão: `"false"`
`num_results`	`int`	Número de resultados a serem retornados. Exemplo: `"5"`
`query_type`	`str`	Algoritmo de busca a ser usado para recuperar resultados. Valores suportados: `"ANN"` (vizinho mais próximo aproximado, default) ou `"HYBRID"` (combina pesquisa de vetor e palavra-chave) padrão: `"ANN"`
`score_threshold`	`float`	Limite mínimo de pontuação de similaridade para filtrar resultados. Resultados com pontuações abaixo desse limite serão excluídos. Exemplo: `"0.7"` Caso não seja especificado, nenhum filtro de pontuação será aplicado.

Para obter informações detalhadas sobre esses parâmetros, consulte a documentação SDK Python do Vector Search.

Exemplo: Configurar resultados máximos e filtros para recuperação de pesquisa vetorial

Este exemplo mostra como usar parâmetros _meta para controlar o comportamento da Busca Vetorial, permitindo consultas dinâmicas do seu agente AI usando o SDKoficial do MCPPython.

Neste cenário, você quer:

Limite sempre os resultados da pesquisa a exatamente 3 itens para tempos de resposta consistentes
Pesquise apenas documentação recente (atualizada após 2024-01-01) para garantir relevância
Use a pesquisa híbrida para maior precisão do que a pesquisa vetorial pura
Retornar apenas colunas específicas (id, texto e metadados)
Inclua as pontuações de similaridade nos resultados.
Excluir resultados com índices de similaridade inferiores a 0,5.
Use o reordenamento nas colunas de texto e título para melhorar a relevância.

Para executar este exemplo, configure seu ambiente Python para gerenciar o desenvolvimento do MCP:

Expanda para ver o exemplo de código.

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

Próximos passos

Databricks gerencia servidores MCP

Argumentos de chamada de ferramenta vs. parâmetros _meta​

Parâmetros do servidor DBSQL MCP _meta​

Exemplo: Especifique um SQL warehouse para consultas DBSQL.​

Parâmetros do servidor MCP de busca vetorial _meta​

Exemplo: Configurar resultados máximos e filtros para recuperação de pesquisa vetorial​

Próximos passos​