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

Conecte clientes aos MCPs da Databricks

info

Visualização

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

Conecte clientes, assistentes AI e IDEs que suportam o Protocolo de Contexto de Modelo (MCP) aos MCPs Databricks . Isso fornece acesso aos dados e ferramentas do Databricks diretamente em seu ambiente de desenvolvimento.

Ao conectar clientes aos MCPs da Databricks, você pode:

  • Acesse funções, tabelas e índices de vetores Unity Catalog a partir do seu IDE ou assistente AI
  • Consulte dados do Databricks diretamente do Claude, Claude Code, 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 Genie Space 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 que melhor se adapte aos seus requisitos de segurança:

Método

MCP externo/externo

MCP personalizado

Nível de segurança

Melhor para

OAuth (recomendado)

Apoiado

Apoiado

Alto nível de permissões com escopo definido e refreshautomática de tokens.

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

Tokens de acesso pessoal

Apoiado

Não suportado

Nível Médio - acesso baseado em tokens com prazo de validade

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 Databricks MCP suportam ambos os tipos de clientes, conforme a especificação de autorização MCP:

  • Clientes públicos : Não é necessário segredo do cliente.
  • 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. Configure as definições da aplicação:
    • 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 a referência de escopos OAuth do Databricks para obter informações sobre os escopos disponíveis).
    • Expiração dos tokens : Defina os tempos de acesso e refresh adequados para os tokens.

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 testar e desinstalar 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 a opção Gerar um segredo do 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 inspetor MCP

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 oferece suporte ao MCP através de sua configuração.

  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 OAuth de usuário para máquina (U2M), teste a conexão com o MCP Inspector. O fluxo OAuth valida as credenciais durante o processo de conexão.

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 registro dinâmico de cliente não são compatíveis com a autenticação OAuth.
  • Suporte access token pessoal para servidores MCP personalizados : Servidores MCP personalizados hospedados em Databricks Apps não oferecem suporte access tokens pessoal para autenticação.

Próximos passos​

Nesta página