Metaparâmetros para servidores MCP gerenciados do Databricks

info

Visualização

Este recurso está em Pré-lançamento público.

Ao criar agentes de AI que usam servidores MCP gerenciados pelo Databricks, use o parâmetro _meta para configurar o comportamento da ferramenta, como limites de resultados, filtros de pesquisa ou seleção de SQL warehouse. Essa abordagem permite que você predefina a configuração, mantendo as queries 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 versus _meta parâmetros

Servidores MCP gerenciados da Databricks lidam com parâmetros de duas maneiras:

• **Argumentos de chamada de ferramenta**: Parâmetros que um LLM geralmente gera dinamicamente com base na entrada do usuário
• _meta parâmetros : Parâmetros de configuração que podem ser predefinidos no código do agente para definir o comportamento de forma determinística.

Parâmetros _meta do servidor MCP do Databricks SQL

O servidor MCP do Databricks SQL oferece suporte aos seguintes parâmetros _meta:

Nome do parâmetro	Tipo	Descrição
warehouse_id	str	O ID do SQL warehouse para usar na execução de consultas. Exemplo: "a1b2c3d4e5f67890" Se não especificado, o sistema seleciona automaticamente um warehouse com base nos recursos e permissões.

Exemplo: especificar um SQL warehouse para consultas Databricks SQL

Este exemplo mostra como usar o parâmetro warehouse_id _meta para especificar qual SQL warehouse executa consultas do servidor MCP do Databricks SQL usando o SDK MCP Python oficial.

Nesse cenário, você deseja:

• Use um SQL warehouse específico para a execução da consulta em vez de deixar o sistema selecionar um automaticamente
• Verifique o desempenho consistente roteando queries para um warehouse dedicado

Para executar este exemplo, configure seu ambiente Python para desenvolvimento MCP gerenciado:

Expandir para ver o exemplo de código

Para encontrar seu ID do SQL warehouse, consulte Conectar 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
                    &quot;name&quot;: &quot;execute_sql&quot;,

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

                    # Meta parameters - specify which warehouse to use
                    &quot;_meta&quot;: {
                        &quot;warehouse_id&quot;: &quot;a1b2c3d4e5f67890&quot;  # 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 Pesquisa de AI _meta

Pesquisa de AI é compatível com os seguintes parâmetros _meta:

Nome do parâmetro	Tipo	Descrição
columns	str	Lista de nomes de colunas separada por vírgulas para retornar nos resultados da pesquisa. Exemplo: "id,text,metadata" Se não especificado, todas as colunas (exceto colunas internas que começam com "__") são retornadas.
columns_to_rerank	str	Lista de nomes de colunas separada por vírgulas cujo conteúdo o modelo de reclassificação usa para reclassificação. O reclassificador usa este conteúdo para reclassificar todos os resultados da pesquisa para melhorar a relevância. Exemplo: "text,title,description" Se não especificado, a reclassificação não é realizada.
filters	str	Strings JSON contendo filtros a serem aplicados à pesquisa. Deve ser um JSON válido. Exemplo: '{"updated_after": "2024-01-01"}' Se não especificado, nenhum filtro é aplicado.
include_score	bool	Se deve incluir a pontuação de similaridade nos resultados retornados. Valores compatíveis: "true" ou "false" default: "false"
num_results	int	Número de resultados a retornar. Exemplo: "5"
query_type	str	Algoritmo de pesquisa a ser usado para recuperar resultados. Valores suportados: "ANN" (vizinho mais próximo aproximado, default) ou "HYBRID" (combina pesquisa vetorial e por palavra-chave) default: "ANN"
score_threshold	float	Limite de pontuação de similaridade mínima para filtrar resultados. Resultados com pontuações abaixo deste limite são excluídos. Exemplo: "0.7" Se não especificado, nenhum filtro de pontuação é aplicado.

Para obter informação detalhada sobre esses parâmetros, consulte a documentação do AI Search SDK Python.

Exemplo: configure os resultados máximos e os filtros para recuperação de Pesquisa de AI

Este exemplo mostra como usar parâmetros _meta para configurar o comportamento da Pesquisa de AI, enquanto permite consultas dinâmicas do seu agente de AI usando o SDK Python MCP oficial.

Nesse cenário, você deseja:

• Sempre limite os resultados da pesquisa a exatamente 3 itens para tempos de resposta consistentes
• Pesquise apenas a documentação recente (atualizada após 01-01-2024) para verificar a relevância.
• Use a busca híbrida para obter melhor precisão do que a busca vetorial pura.
• Retorne apenas colunas específicas (ID, texto e metadados)
• Inclua as pontuações de similaridade nos resultados
• Exclua resultados com pontuações de similaridade abaixo de 0,5
• Use reclassificação em colunas de texto e título para melhorar a relevância

Para executar este exemplo, configure seu ambiente Python para desenvolvimento MCP gerenciado:

Expandir 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/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
                    &quot;name&quot;: &quot;YOUR_CATALOG__YOUR_SCHEMA__YOUR_INDEX_NAME&quot;,

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

                    # Meta parameters - preset configuration to control search behavior
                    &quot;_meta&quot;: {
                        &quot;num_results&quot;: &quot;3&quot;,  # Limit to 3 results for consistent performance
                        &quot;filters&quot;: '{&quot;updated_after&quot;: &quot;2024-01-01&quot;}',  # JSON string for date filtering
                        &quot;query_type&quot;: &quot;HYBRID&quot;,  # Use hybrid search for better relevance
                        &quot;columns&quot;: &quot;id,text,metadata&quot;,  # Return only specific columns
                        &quot;score_threshold&quot;: &quot;0.5&quot;,  # Filter out results with similarity score &lt; 0.5
                        &quot;include_score&quot;: &quot;true&quot;,  # Include similarity scores in results
                        &quot;columns_to_rerank&quot;: &quot;text,title&quot;  # 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 os passos

• Servidores MCP gerenciados da Databricks