Pular para o conteúdo principal
Última atualização em

Servidor MCP Genie One

O servidor MCP do Genie One é um MCP fornecido pelo Databricks que expõe o Genie como uma ferramenta conversacional sobre o Model Context Protocol (MCP), aproveitando o Chat no Genie One. Um cliente ou agente MCP envia uma pergunta em linguagem natural, e o Genie pesquisa seus dados corporativos, escreve SQL e retorna uma resposta baseada na Genie Ontology com links diretos de retorno para suas fontes citadas do Databricks.

Conecte qualquer cliente ou agente MCP para fundamentar suas perguntas de dados nas percepções confiáveis do Genie. Clientes que suportam Apps MCP podem renderizar uma View interativa que mostra o progresso, as visualizações e os resultados do Genie em linha.

As permissões do Unity Catalog são sempre aplicadas, portanto, usuários e agentes só podem fazer query de dados que têm permissão para acessar.

Use este servidor para analítica em todo o seu workspace: perguntas de negócios feitas em linguagem natural, onde a precisão depende da compreensão do que seus dados significam. O Genie resolve termos de negócios, definições de métricas e relacionamentos entre tabelas por meio da Genie Ontology, sua camada semântica governada, que produz respostas mais precisas do que um agente escrevendo SQL diretamente em tabelas brutas.

dica

Para fazer uma query em um Genie Agent com curadoria do Python, use exemplos da ferramenta AI Bridge. Para fazer uma query em um agente específico via MCP, consulte o servidor MCP do Genie Agent. Para chamar o Genie One de um aplicativo sem MCP, use a API do Genie One.

Requisitos​

Para chamar o servidor MCP Genie One, um usuário ou service principal precisa do seguinte:

  • EXECUTE em system.ai.genie_one_mcp. Seu tipo de objeto protegível é mcp_service.
  • USE CATALOG no catálogo system e USE SCHEMA no esquema system.ai.
  • Atribuição ao workspace.

Para verificar as permissões efetivas de um chamador com a CLI do Databricks, execução:

Bash
databricks grants get-effective mcp_service system.ai.genie_one_mcp --principal someone@example.com

Para conceder EXECUTE, execução:

Bash
databricks grants update mcp_service system.ai.genie_one_mcp \
  --json '{"changes": [{"principal": "someone@example.com", "add": ["EXECUTE"]}]}'

Para conceder acesso a um MCP fornecido pelo Databricks, um administrador do metastore deve primeiro conceder a si mesmo MANAGE no esquema system.ai. Veja Compartilhar um MCP.

Access through Unity Gateway​

O servidor MCP do Genie One é um MCP fornecido pela Databricks, system.ai.genie_one_mcp, governado por meio do Unity Gateway.

Invoque o MCP em sua URL do Unity Gateway, com seu nome totalmente qualificado do Unity Catalog no caminho e seu ID de workspace no parâmetro de query o:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>

Para obter o ID do workspace sem a UI, use um dos seguintes:

  • O valor o= no seu URL de workspace.
  • O cabeçalho x-databricks-org-id em qualquer resposta da API REST do Databricks.
  • WorkspaceClient().get_workspace_id() no SDK do Databricks para Python.

Ao conectar-se com autenticação de usuário em nome de, inclua o escopo OAuth ai-gateway. Para controlar o acesso e aplicar políticas, consulte Gerenciar um MCP. Para adicionar o MCP a um agente, consulte Chamar ferramentas MCP de um agente Python. Para conectar clientes externos como Cursor ou Claude Desktop, consulte Agentes de trabalho e codificação suportados.

atenção

Descontinuado

O endpoint Beta, https://<workspace-hostname>/api/2.0/mcp/genie, está obsoleto e chegará ao fim da vida útil em 30 de novembro de 2026. Após essa data, as solicitações para o endpoint Beta falharão. Mova todas as cargas de trabalho para o MCP system.ai.genie_one_mcp de disponibilidade geral antes disso.

Os nomes de ferramentas e argumentos são os mesmos em ambos os Endpoint. Para mover um cliente do endpoint Beta, atualize sua configuração MCP:

  • Substitua a URL do servidor por https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>.
  • Se o cliente usar OAuth, solicite o escopo ai-gateway em vez do escopo genie.
  • Verifique se os chamadores têm as permissões em Requisitos.

Conecte agentes de AI ao Genie One MCP​

Para conectar um agente de codificação ou outro cliente MCP, configure o cliente para se conectar à URL do Unity Gateway MCP https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>. Siga a configuração para agentes de codificação ou outros clientes MCP.

Para view seus MCPs e seus URLs, vá para o seu Workspace e selecione Unity Gateway > MCPs . Para listar MCPs fornecidos pelo Databricks com a API REST, chame GET /api/2.1/unity-catalog/mcp-services?parent=schemas/system.ai. Consulte Encontrar um MCP.

Chamar via Python com o MCP SDK​

O servidor usa o transporte HTTP transmitível e aceita um token do Databricks em um cabeçalho Authorization: Bearer <token>. O exemplo a seguir usa o MCP Python SDK e o Databricks SDK para Python para fazer uma pergunta, verificar até que o Genie termine e, em seguida, fazer uma pergunta de acompanhamento na mesma conversa.

Instale os pacotes:

Bash
pip install mcp databricks-sdk

Faça a execução do exemplo:

Python
import asyncio

from databricks.sdk import WorkspaceClient
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

w = WorkspaceClient()
url = (
    f"{w.config.host}/ai-gateway/mcp-services/system.ai.genie_one_mcp"
    f"?o={w.get_workspace_id()}"
)


async def ask(session, question, conversation_id=None):
    args = {"question": question}
    if conversation_id:
        args["conversation_id"] = conversation_id
    state = (await session.call_tool("genie_ask", args)).structuredContent

    # Poll until Genie finishes: completed, incomplete, or failed.
    while state["status"] == "in_progress":
        poll = await session.call_tool(
            "genie_poll_response",
            {
                "conversation_id": state["conversation_id"],
                "response_id": state["response_id"],
            },
        )
        state = poll.structuredContent
    return state


async def main():
    # w.config.authenticate() returns {"Authorization": "Bearer <token>"}.
    async with streamablehttp_client(url, headers=w.config.authenticate()) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])

            first = await ask(session, "What were total sales last month?")
            print(first["status"], first.get("final_answer"))

            follow_up = await ask(
                session, "Break that down by region.", first["conversation_id"]
            )
            print(follow_up["status"], follow_up.get("final_answer"))


asyncio.run(main())

O exemplo não solicita notificações de progresso, portanto, genie_ask retorna imediatamente com status: in_progress, e o cliente consulta genie_poll_response para obter a resposta.

Plugins do Databricks Genie para ChatGPT, Claude e Grok Bot/Cursor​

Os plugins do Databricks Genie conectam o ChatGPT, o Claude e o Grok Bot/Cursor ao Genie One MCP. Eles usam aplicativos OAuth default, portanto, os usuários fazem login com sua account Databricks e um administrador não precisa criar um aplicativo OAuth.

Um administrador configura o plugin primeiro. Em seguida, cada usuário se conecta a ele e faz login.

nota

Se o seu workspace restringir o acesso de rede de entrada, um administrador do Databricks deverá permitir o tráfego do ChatGPT ou Claude; caso contrário, o plugin não conseguirá se conectar. Consulte Permitir plataformas de parceiros em políticas de entrada baseadas em contexto.

Para configurar o plugin, um administrador do ChatGPT deve fazer o seguinte:

  1. Nas configurações do seu workspace do ChatGPT, clique em Plugins .
  2. Procure por Databricks Genie .
  3. Clique em Create from padrão .
  4. Insira o URL do seu workspace Databricks. Se você usar um URL personalizado, inclua seu ID do workspace como ?o=<workspace-id>.
  5. Clique em Criar rascunho .
  6. Clique em Publicar .

Para se conectar, cada usuário deve fazer o seguinte:

  1. No ChatGPT, abra a página Plugins .
  2. Procure por Databricks Genie .
  3. No plugin que seu administrador configurou, clique em Connect .
  4. Quando o ChatGPT o redirecionar, faça login com sua account Databricks.

Para mais informações, consulte o plugin ChatGPT Genie.

Ferramentas disponíveis​

O servidor MCP Genie One expõe as seguintes ferramentas. Na prática, um agente invoca genie_ask (ou view_ask em clientes de aplicativos MCP) para fazer uma pergunta; o agente gerencia as ferramentas restantes em seu nome enquanto trabalha na resposta.

Ferramenta

Descrição

genie_ask

Faça uma pergunta de dados em linguagem natural ao Genie e comece uma resposta. Retorna conversation_id, response_id e status. Passe um conversation_id para continuar uma conversa anterior.

genie_poll_response

Obtenha o estado mais recente de uma resposta em andamento ou concluída, incluindo os passos de progresso, a resposta final e links diretos para suas fontes do Databricks.

genie_get_query_result

Busque o resultado SQL completo, incluindo esquema de coluna e linhas, para uma query que o Genie executou. Chame-o depois que genie_poll_response reportar status: completed. Usa conversation_id e response_id com os quais você polling, mais item_id da query de genie_poll_response, em structuredContent.query_items[].item_id.

genie_cancel_response

Solicitar o cancelamento de um turno do Genie em andamento.

view_ask

Faça uma pergunta ao Genie e abra a view interativa. Oferecido em vez de genie_ask para clientes de aplicativos MCP, e preferencial quando disponível.

Ferramenta

Descrição

genie_ask

Faça uma pergunta de dados em linguagem natural ao Genie e comece uma resposta. Retorna conversation_id, response_id e status. Passe um conversation_id para continuar uma conversa anterior.

genie_poll_response

Obtenha o estado mais recente de uma resposta em andamento ou concluída, incluindo os passos de progresso, a resposta final e links diretos para suas fontes do Databricks.

genie_get_query_result

Busque o resultado SQL completo, incluindo esquema de coluna e linhas, para uma query que o Genie executou. Chame-o depois que genie_poll_response reportar status: completed. Usa conversation_id e response_id com os quais você polling, mais item_id da query de genie_poll_response, em structuredContent.query_items[].item_id.

genie_cancel_response

Solicitar o cancelamento de um turno do Genie em andamento.

view_ask

Faça uma pergunta ao Genie e abra a view interativa. Oferecido em vez de genie_ask para clientes de aplicativos MCP, e preferencial quando disponível.

Faça uma pergunta​

Como o Genie faz a execução de um agente que pesquisa dados e executa SQL, as respostas são assíncronas. Você (ou seu agente) invoca genie_ask com uma pergunta; o agente então gerencia o restante da troca automaticamente. Um fluxo típico tem a seguinte aparência:

  1. genie_ask começa a resposta e retorna um conversation_id e response_id com status: in_progress. O Genie continua trabalhando em segundo plano.
  2. O agente pesquisa genie_poll_response até que a resposta seja concluída, exibindo progress_steps e um narration_instruction ao longo do caminho para mantê-lo informado.
  3. Quando status é completed (ou incomplete / failed), o agente retorna a resposta renderizada, incluindo um link direto Explore in Databricks para a conversa completa e quaisquer visualizações que o Genie produziu.

Para continuar a mesma conversa, a pergunta de acompanhamento reutiliza o conversation_id anterior.

Aplicativo MCP​

O servidor MCP do Genie One fornece um aplicativo MCP, uma extensão que permite que um servidor retorne uma view interativa em vez de texto simples. Em clientes que suportam aplicativos MCP, o servidor retorna uma View interativa: um painel incorporado no cliente que mostra o progresso, as visualizações e a resposta final do Genie conforme a conversa se desenrola, em vez de uma resposta apenas em texto.

O aplicativo Genie One MCP renderizando um gráfico de barras, métricas de resumo e citações da Genie Ontology dentro do Claude Desktop.

O aplicativo Genie One MCP renderizando um gráfico de barras, métricas de resumo e citações da Genie Ontology dentro do Claude Desktop.

Nenhuma configuração adicional é necessária. Os clientes que oferecem suporte a aplicativos MCP recebem automaticamente a View interativa. Clientes que não continuam a receber resultados de texto.

Considerações​

  • Permissões : As permissões do Unity Catalog são aplicadas em cada solicitação, portanto, os resultados são limitados ao que o usuário pode acessar.
  • Autenticação de usuário : a autenticação OAuth em nome do usuário é recomendada, seguindo as melhores práticas de governança de dados e permitindo o clickthrough suave para as fontes do Genie. A autenticação de service principal também é compatível com cargas de trabalho programáticas e automatizadas. Qualquer token do Databricks enviado em um header Authorization: Bearer funciona, incluindo OAuth user-to-machine (U2M), OAuth machine-to-machine (M2M) e personal access tokens, portanto, um fluxo OAuth do navegador não é necessário. Consulte Autenticação de entrada compatível.
  • Configuração : O servidor respeita sua configuração do Genie One no Databricks. Ajuste e configure o comportamento do Genie lá. Consulte Bate-papo no Genie One.
  • Cadência de polling : aguarde a conclusão da chamada genie_poll_response anterior antes de realizar o polling novamente.
  • Tamanho do resultado : Para proteger a janela de contexto do modelo, genie_ask e genie_poll_response retornam resultados de query truncados. Quando um agente precisa do resultado completo, ele pode chamar genie_get_query_result para recuperar o esquema completo e as linhas. Resultados muito grandes ainda estão sujeitos a um limite de tamanho; se ele for excedido, a resposta será truncada.
  • SQL Warehouse : To execução querys on a specific SQL Warehouse, pass warehouse_id in the _meta parameters on genie_ask or view_ask.
  • Preços : O servidor MCP Genie One usa o Chat no Genie One. Consulte preços do Genie.

Solução de problemas​

  • Routine or Model ... does not exist ou MCP is not a valid securable type ao verificar ou conceder permissões : Use mcp_service como o tipo securable, não function ou mcp. Os tipos function e mcp não resolvem o MCP.
  • genie_poll_response não retorna query_items após a conclusão da resposta : Obtenha o item_id do comentário Tool-call IDs no final do texto da consulta ou capture structuredContent.query_items[].item_id de uma consulta anterior enquanto a resposta estava em trânsito.
  • item_id não resolve em genie_get_query_result : Um item_id válido parece pub_..._output. Não passe um ID de incorporação query_... dos marcadores de comentário da tabela de resultados como item_id, pois ele não será resolvido.

Outros recursos​

Nesta página