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

Conecte clientes não Databricks aos servidores MCP Databricks

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Conecte clientes nãoDatabricks (externos), assistentes de AI e IDEs que suportam o Model Context Protocol (MCP) aos servidores MCP Databricks . Isso fornece acesso aos dados e ferramentas do Databricks diretamente no seu ambiente de desenvolvimento.

Ao conectar clientes externos aos servidores MCP do Databricks, você pode:

  • Acesse as funções, tabelas e índices vetoriais do Unity Catalog em seu assistente de IDE ou AI
  • Consulte dados do Databricks diretamente do Claude, Cursor, Replit ou outras ferramentas compatíveis com MCP.

Pré-requisitos​

  • URLs do servidor : Obtenha os URLs de servidor apropriados para o servidor Databricks MCP que você deseja usar:

  • Acesso ao recurso : Verifique se você tem acesso aos servidores MCP que deseja usar e a quaisquer recursos subjacentes. Por exemplo, se você usar o servidor Genie gerencia MCP, precisará de acesso ao espaço Genie subjacente.

  • Acesso à rede : Se o seu workspace Databricks tiver restrições de acesso por IP, adicione os endereços IP de saída do seu cliente à lista de permissões para permitir que ele se conecte ao seu workspace.

    • Siga as instruções na documentação sobre listas de acesso IPworkspace e listas de acesso IPaccount para verificar se existem restrições em vigor.
    • Se as listas de acesso IP estiverem ativadas, identifique os IPs de saída do seu cliente. Essas informações geralmente estão disponíveis na documentação do cliente; por exemplo, a Claude documenta seus endereços IP de saída aqui.
    • Certifique-se de que os endereços IP de saída do seu cliente sejam adicionados à lista.

Métodos de autenticação​

Escolha o método de autenticação mais adequado aos seus requisitos de segurança:

Método

gerenciar/MCP externo

MCP personalizado

Nível de segurança

Melhor para

OAuth (recomendado)

Suportado

Suportado

Alta - permissões com escopo, tokens automáticos refresh

Uso de produção, ambientes de equipe, acesso de longo prazo

Tokens de acesso pessoal

Suportado

Não suportado

Médio - acesso baseado em tokens com expiração

Desenvolvimento individual, testes, acesso de curto prazo

Conecte clientes usando autenticação OAuth​

OAuth fornece autenticação segura com permissões definidas e refresh automática de tokens.

nota

Os servidores MCP do Databricks suportam ambos os tipos de clientes, de acordo com a especificação de autorização MCP:

  • Clientes públicos : Nenhum segredo de cliente necessário
  • Clientes confidenciais : Incluir segredo do cliente

Obtenha o URL de redirecionamento OAuth do seu cliente.​

Cada cliente MCP requer URLs de redirecionamento OAuth específicos para os retornos de chamada de autenticação. Os padrões comuns de URLs de redirecionamento incluem:

  • Clientes baseados na Web : https://<domain>/oauth/callback ou https://<domain>/api/mcp/auth_callback
  • Ferramentas de desenvolvimento local : http://localhost:<port>/oauth/callback

Consulte a documentação do seu cliente para encontrar os URLs de redirecionamento exatos necessários.

Crie o aplicativo OAuth do Databricks.​

Solicite a um administrador account que crie um aplicativo OAuth Databricks . Recupere o ID do cliente e, se o seu cliente o exigir, o segredo do cliente.

Crie um aplicativo OAuth Databricks usando o consoleaccount:

  1. No console account Databricks , acesse Configurações > Conexões de aplicativos > Adicionar conexão .
  2. Defina as configurações do aplicativo:
    • Nome : Insira um nome descritivo para seu aplicativo OAuth (por exemplo, claude-mcp-client, mcp-inspector)
    • URLs de redirecionamento : Adicione os URLs de redirecionamento exigidos pelo seu cliente externo.
    • Tipo de cliente : Para clientes públicos (baseados em navegador, dispositivos móveis), desmarque a opção Gerar um segredo do cliente . Para clientes confidenciais (lado do servidor), mantenha essa opção marcada.
    • Escopos : Configure os escopos da API (consulte Configurar escopos OAuth abaixo)
    • Expiração dos tokens : Defina os tempos de acesso e refresh adequados para os tokens.

Configurar escopos OAuth​

Os escopos do OAuth controlam quais APIs do Databricks seu cliente pode acessar. Para a maioria dos casos de uso, utilize o escopo all-apis , que concede acesso a todas as APIs do Databricks e é a opção mais simples.

Para um controle mais granular, você pode especificar escopos específicos do MCP em vez de all-apis:

Tipo de servidor MCP

Escopo(s) necessário(s)

Genie spaces

mcp.genie

Funções Unity Catalog do MCP

mcp.functions

Busca vetorial MCP

mcp.vectorsearch

MCP Databricks SQL

mcp.sql, sql.warehouses, sql.statement-execution

funções externas do MCP

mcp.external

Para obter mais informações sobre como declarar escopos API REST e usá-los com agentes, consulte Declarar escopos API REST ao registrar o agente.

Configurar acesso à rede (opcional)​

Se o seu workspace Databricks tiver restrições de acesso por IP, adicione os endereços IP de saída do seu cliente à lista de permissões workspace . Caso contrário, o workspace bloqueará as solicitações de autenticação do seu cliente. Veja gerenciar listas de acesso IP.

Configure seu cliente​

Após criar o aplicativo OAuth no Databricks, configure seu cliente MCP específico com as credenciais OAuth. Cada cliente possui seu próprio método de configuração. Consulte os exemplos específicos da plataforma a seguir para obter instruções detalhadas sobre os clientes MCP mais populares.

Exemplos de OAuth​

Os exemplos a seguir mostram como configurar clientes MCP específicos com autenticação OAuth. Siga primeiro os passos genéricos de configuração do OAuth na seção anterior e, em seguida, use estes exemplos para configurar seu cliente específico.

O MCP Inspector é uma ferramenta de desenvolvimento para teste e depuração de servidores MCP.

Inspetor MCP

Siga as instruções de configuração da autenticação OAuth acima com estas configurações específicas do Inspector:

  • URLs de redirecionamento:

    • http://localhost:6274/oauth/callback
    • http://localhost:6274/oauth/callback/debug

  • Tipo de cliente : Público (desmarque Gerar um segredo de cliente )

Configurar o MCP Inspector:

  1. execução do inspetor: npx @modelcontextprotocol/inspector.
  2. Defina o tipo de transporte como Streamable HTTP.
  3. Insira o URL do seu servidor Databricks MCP.
  4. Na seção Autenticação , adicione seu ID de cliente OAuth.
  5. Clique em Abrir configurações de autenticação e escolha Fluxo guiado ou Fluxo rápido .
  6. Após a autenticação bem-sucedida, cole o access token em Tokens Bearer na seção Autenticação de tokensAPI .
  7. Clique em Conectar .

Fluxo de autenticação do MCP Inspector

Conecte clientes usando autenticação access token pessoal (PAT).​

access tokens pessoal oferecem um método de autenticação mais simples, adequado para desenvolvimento individual, testes e acesso de curto prazo aos servidores Databricks MCP.

nota

access tokens pessoal são suportados apenas para servidores gerenciados e servidores MCP externos. Servidores MCP personalizados exigem autenticação OAuth.

  1. Gere um access token pessoal no seu workspace Databricks . Consulte Autenticar com access tokens pessoal Databricks (legado).

  2. Configurar acesso à rede (opcional).

    Se o seu workspace Databricks tiver restrições de acesso por IP, adicione os endereços IP de saída do seu cliente à lista de permissões. Consulte a documentação do seu cliente ou a configuração de rede do seu ambiente de implantação para obter os endereços IP necessários.

  3. Configure seu cliente.

    Após gerar o PAT, configure seu cliente MCP para usá-lo para autenticação. Cada cliente possui seu próprio método de configuração. Consulte os exemplos específicos da plataforma abaixo para obter instruções detalhadas sobre os clientes MCP mais populares.

Exemplos de PAT​

Os exemplos a seguir mostram como configurar clientes MCP específicos com autenticação access token pessoal. Siga primeiro a configuração de autenticação PAT acima e, em seguida, use estes exemplos para configurar seu cliente específico.

O Cursor suporta MCP por meio de sua configuração de configurações.

  1. Abra as configurações do cursor.

  2. Adicione a seguinte configuração (adapte o URL para o servidor MCP escolhido):

    JSON
    {
      "mcpServers": {
        "uc-function-mcp": {
          "type": "streamable-http",
          "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
          "headers": {
            "Authorization": "Bearer <YOUR_TOKEN>"
          },
          "note": "Databricks UC function"
        }
      }
    }

  3. Substitua <your-workspace-hostname> pelo hostname do seu workspace Databricks .

  4. Substitua <YOUR_TOKEN> pelo seu access token pessoal.

Solucionar problemas de conexão​

Siga estes passos de resolução de problemas para diagnosticar e solucionar problemas comuns de conexão.

Validar autenticação​

Verifique se suas credenciais de autenticação estão configuradas corretamente antes de testar a conexão.

Para autenticação de entidade de serviço com OAuth máquina a máquina (M2M), teste suas credenciais usando a CLI do Databricks.

Bash
DATABRICKS_CLIENT_ID=<your-client-id> DATABRICKS_CLIENT_SECRET=<your-client-secret> databricks auth describe

Este comando valida a configuração da sua entidade de serviço e exibe informações sobre a identidade autenticada. Se o comando retornar um erro, revise a configuração da sua entidade de serviço e certifique-se de que:

  • A entidade de serviço foi criada na sua account Databricks
  • O ID do cliente e o segredo do cliente estão configurados corretamente.
  • A entidade de serviço possui permissões apropriadas para acessar o recurso necessário

Verifique a configuração da rede.​

Restrições de rede podem impedir que clientes externos se conectem ao seu workspace Databricks . Certifique-se de que todas as políticas de lista de acesso IP Databricks estejam configuradas para permitir que seu cliente se conecte à sua account e workspace Databricks . Consulte os pré-requisitos.

Identificar problemas de conexão específicos do cliente​

Tente conectar-se com um cliente MCP diferente para verificar se o problema persiste. A Databricks recomenda realizar os testes com o MCP Inspector. Se a sua conexão funcionar com o MCP Inspector, mas falhar com o seu cliente, o problema provavelmente está na configuração do seu cliente. Contate o fornecedor do cliente para obter mais suporte.

Reporte problemas ao suporte da Databricks.​

Se você continuar a ter problemas de conexão após concluir estas etapas de solução de problemas:

  1. Analise os logs do seu cliente MCP, como Claude, Cursor ou MCP Inspector, em busca de mensagens de erro e rastreamentos de pilha.

  2. Reúna as seguintes informações de diagnóstico:

    • Método de autenticação utilizado (OAuth ou PAT)
    • URL do servidor MCP
    • Mensagens de erro do cliente
    • Detalhes da configuração de rede (restrições de IP, regras de firewall)

  3. Entre em contato com o suporte e compartilhe as informações de diagnóstico para resolver o problema.

Limitações​

  • Registro dinâmico de clientes : Databricks não oferece suporte a fluxos OAuth de registro dinâmico de clientes para servidores MCP gerenciados, externos ou personalizados. Clientes externos e IDEs que exigem o Registro Dinâmico de Cliente não são suportados usando a autenticação OAuth.
  • Suporte access token pessoal de servidor MCP personalizado : servidores MCP personalizados hospedados em aplicativos Databricks não oferecem suporte access tokens pessoal para autenticação.

Próximos passos​