Conectar clientes que não são do Databricks aos servidores MCP do Databricks

Conecte clientes não Databricks (externos), assistentes de IA e IDEs que dão suporte ao PROTOCOLO MCP (Protocolo de Contexto de Modelo) aos servidores MCP do Databricks. Isso fornece acesso a dados e ferramentas do Databricks diretamente em seu ambiente de desenvolvimento.

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

• Acesse funções do Catálogo Unity, tabelas e índices de vetor no seu IDE ou assistente de IA
• Consultar dados do Databricks diretamente de Claude, Cursor, Replit ou outras ferramentas habilitadas para MCP

Prerequisites

• URLs do servidor: obtenha as URLs de servidor apropriadas para o servidor MCP do Databricks que você deseja usar:
  • Servidores MCP gerenciados
  • Servidores MCP externos
  • Servidores MCP personalizados
• Acesso a recursos: verifique se você tem acesso aos servidores MCP que deseja usar e a todos os recursos subjacentes. Por exemplo, se você usar o servidor MCP gerenciado pelo Genie, precisará de acesso ao espaço subjacente do Genie.
• Acesso à rede: se o workspace do Databricks tiver restrições de acesso IP, adicione os endereços IP de saída do cliente à lista de permissões para permitir que ele se conecte ao seu workspace:
  • Siga a documentação para listas de acesso IP do workspace e listas de acesso IP da conta para verificar se há alguma restrição ativa.
  • Se as listas de acesso ip estiverem habilitadas, identifique os IPs de saída do cliente. Essas informações geralmente estão disponíveis na documentação do cliente; por exemplo, Claude documenta seus endereços IP de saída aqui.
  • Verifique se os IPs de saída do cliente são adicionados à lista.

Métodos de autenticação

Escolha o método de autenticação que melhor atenda aos seus requisitos de segurança:

Conectar clientes usando a autenticação OAuth

O OAuth fornece autenticação segura com permissões com escopo e atualização automática de token.

Obter a URL de redirecionamento do OAuth do cliente

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

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

Verifique a documentação do cliente para localizar as URLs de redirecionamento exatas necessárias.

Criar o aplicativo OAuth do Databricks

Fazer com que um administrador de conta crie um aplicativo OAuth do Databricks. Recupere a ID do cliente e, se o cliente exigir, o segredo do cliente.

Baseado em interface do usuário (Console de Conta)

Crie um aplicativo OAuth do Databricks usando o console da conta:

1. No console da conta do Databricks, vá para Configurações>Conexões> de AplicativoAdicionar 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: adicionar as URLs de redirecionamento exigidas pelo seu cliente externo
   • Tipo de cliente: para clientes públicos (baseado em navegador, móvel), desmarque Gerar um segredo do cliente. Para clientes confidenciais (lado do servidor), mantenha-o verificado.
   • Escopos: configurar os escopos da API (consulte Configurar escopos OAuth abaixo)
   • Expiração do token: definir os horários apropriados de acesso e atualização de token

CLI

Crie um aplicativo OAuth do Databricks usando a CLI do Databricks:

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

Substitua <your-client-redirect-url> pela URL de redirecionamento real do cliente.

Configurar escopos OAuth

Os escopos do OAuth controlam quais APIs do Databricks seu cliente pode acessar. Para a maioria dos casos de uso, use o all-apis escopo, 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:

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

Configurar o acesso à rede (opcional)

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

Configurar seu cliente

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

Exemplos de OAuth

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

Inspetor MCP

O McP Inspector é uma ferramenta de desenvolvedor para testar e depurar servidores MCP.

Siga a configuração de autenticação OAuth acima com estas configurações específicas do Inspetor:

• URLs de redirecionamento:
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug
• Tipo de cliente: Público (desmarcar Gerar um segredo do cliente)

Configurar o Inspetor do MCP:

1. Execute o inspetor: npx @modelcontextprotocol/inspector.
2. Definir tipo de transporte como Streamable HTTP.
3. Insira a URL do servidor MCP do Databricks.
4. Na seção Autenticação , adicione sua ID do cliente OAuth.
5. Clique em Abrir Configurações de Autenticação e escolha Fluxo Guiado ou Rápido .
6. Após a autenticação bem-sucedida, cole o token de acesso no Token de Portador na seção Autenticação de Token de API .
7. Clique em Conectar.

Conectores claude

Conecte Claude a servidores MCP gerenciados e externos do Databricks usando Claude Connectors com Remote MCP.

Siga a configuração de autenticação OAuth acima com estas configurações específicas de Claude:

• URL de redirecionamento: https://claude.ai/api/mcp/auth_callback e https://claude.com/api/mcp/auth_callback
• Lista de permissões de IP (se necessário): adicionar os endereços IP de saída de Claude

Configurar Claude:

1. Vá para Configurações>Conectores no aplicativo Claude.
2. Clique em Adicionar conector personalizado.
3. Insira a URL do servidor MCP do Databricks.
4. Insira a ID do cliente do aplicativo OAuth.
5. Clique em Adicionar para concluir.

Cursor/Windsurf

Para conectar com segurança um IDE local como Cursor ou Windsurf a um servidor MCP do Databricks, use mcp-remote com o OAuth. Siga as instruções do repositório remoto mcp para configurar o mcp-remote. Em seguida, siga a configuração de autenticação OAuth para verificar se o OAuth está configurado corretamente.

Configurar Cursor ou Windsurf:

1. Localize o arquivo de configuração do MCP:

   • Cursor: ~/.cursor/mcp.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

2. No arquivo de configuração, adicione o servidor MCP:

   Para clientes OAuth confidenciais (com segredo do cliente):

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
         ]
       }
     }
   }
   

   Para clientes OAuth públicos (sem segredo do cliente):

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
         ]
       }
     }
   }
   

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

4. Defina a variável MCP_REMOTE_CLIENT_ID de ambiente com a ID do cliente OAuth. Para clientes confidenciais, também defina MCP_REMOTE_CLIENT_SECRET com o segredo do cliente.

Conectar clientes usando a autenticação PAT (token de acesso pessoal)

Os tokens de acesso pessoal fornecem um método de autenticação mais simples adequado para desenvolvimento individual, teste e acesso de curto prazo aos servidores MCP do Databricks.

1. Gere um token de acesso pessoal no workspace do Databricks. Consulte Autenticar com tokens de acesso pessoal do Azure Databricks (herdado).

2. Configurar o acesso à rede (opcional).

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

3. Configure seu cliente.

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

Exemplos de PAT

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

Cursor

O cursor dá suporte ao MCP por meio de sua configuração de configurações.

1. Abra as configurações do Cursor.

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

   {
     "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 nome do host do workspace do Databricks.

4. Substitua <YOUR_TOKEN> pelo seu token de acesso pessoal.

Claude Desktop

O Claude Desktop pode se conectar aos servidores MCP do Databricks usando o mcp-remote.

1. Localize o claude_desktop_config.json arquivo:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

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

   {
     "mcpServers": {
       "uc-function-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
           "--header",
           "Authorization: Bearer <YOUR_TOKEN>"
         ]
       }
     }
   }
   

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

4. Substitua <YOUR_TOKEN> pelo seu token de acesso pessoal.

5. Reinicie o Claude Desktop para que as alterações entrem em vigor.

Replitar

O Replit dá suporte à conexão com servidores MCP do Databricks por meio da configuração personalizada do servidor MCP.

1. No workspace Replit, clique em Adicionar Servidor MCP.

2. Insira a URL do servidor MCP do Databricks, por exemplo:

   https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
   

3. Adicione um cabeçalho personalizado:

   • Chave: Authorization
   • Valor: Bearer <YOUR_TOKEN>

Consulte a documentação do REPlit MCP.

Solucionar problemas de conexão

Siga estas etapas de solução de problemas para diagnosticar e resolver 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.

Principal de serviço (M2M)

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

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

Este comando valida a configuração do principal do serviço e exibe informações sobre a identidade autenticada. Se o comando retornar um erro, examine a configuração do principal de serviço e verifique:

• No Databricks, o service principal foi criado na sua conta.
• A ID do cliente e o segredo do cliente estão configurados corretamente
• A entidade de serviço possui as permissões apropriadas para acessar os recursos necessários

OAuth de Usuário para Máquina (U2M)

Para autenticação U2M (usuário para máquina) do OAuth, teste a conexão com o Inspetor MCP. O fluxo OAuth valida as credenciais durante o processo de conexão.

Verificar a configuração de rede

As restrições de rede podem impedir que clientes externos se conectem ao workspace do Databricks. Verifique se todas as políticas de lista de acesso ip do Databricks estão configuradas para permitir que seu cliente se conecte à sua conta e ao workspace do Databricks. Consulte Pré-requisitos.

Relatar problemas ao suporte do Databricks

Se você continuar enfrentando problemas de conexão depois de concluir estas etapas de solução de problemas:

1. Examine os logs de seu cliente MCP (Claude, Cursor, McP Inspector etc.) para obter mensagens de erro e rastreamentos de pilha.

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

   • Método de autenticação usado (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. Contate o suporte e compartilhe as informações de diagnóstico para resolver o problema.

Limitações

• Registro dinâmico do cliente: o Databricks não dá suporte a fluxos OAuth de registro de cliente dinâmico para servidores MCP gerenciados, externos ou personalizados. Não há suporte para clientes externos e IDEs que exigem o Registro Dinâmico de Cliente usando a autenticação OAuth.
• Suporte personalizado ao token de acesso pessoal do servidor MCP: os servidores MCP personalizados hospedados nos Aplicativos do Databricks não dão suporte a tokens de acesso pessoal para autenticação.
• Autorização em nome: os servidores MCP personalizados hospedados nos Aplicativos do Databricks não dão suporte à autorização em nome do usuário.

Próximas etapas

• Usar servidores MCP gerenciados para conectar agentes aos dados do Catálogo do Unity
• Usar servidores MCP externos para acessar serviços de terceiros
• Hospedar servidores MCP personalizados para ferramentas específicas da organização