Conectar clientes que não são Databricks a servidores Databricks MCP

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

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

• Acesse funções, tabelas e índices vetoriais do Unity Catalog a partir do seu assistente IDE ou AI
• Consulta os dados do Databricks diretamente a partir do Claude, Cursor, Replit, ou outras ferramentas com MCP

Prerequisites

• URLs do servidor: Obtenha os URLs de servidor apropriados para o servidor MCP da Databricks que pretende usar:
  • Servidores MCP gerenciados
  • Servidores MCP externos
  • Servidores MCP personalizados
• Acesso a recursos: verifique se sua conta tem acesso aos recursos do Catálogo Unity que você deseja usar
• Acesso à rede: se o seu espaço de trabalho tiver restrições de IP, permita listar os endereços IP do seu cliente

Métodos de autenticação

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

Ligue clientes usando autenticação OAuth

O OAuth fornece autenticação segura com permissões definidas e atualização automática dos tokens.

Obtenha o URL de redirecionamento OAuth do seu cliente

Cada cliente MCP requer URLs específicos de redirecionamento OAuth para callbacks de autenticação. 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 local: http://localhost:<port>/oauth/callback

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

Criar a aplicação Databricks OAuth

Peça a um administrador de conta para criar uma aplicação Databricks OAuth. Obtenha o ID do cliente e, se o seu cliente precisar, a chave secreta do cliente.

Baseado na Interface de Usuário (Console de Gestão de Conta)

Crie uma aplicação Databricks OAuth usando a consola da conta:

1. Na consola da conta Databricks, vá a Definições>Aplicação Ligações>Adicionar ligação.

2. Configure as definições da aplicação:

   • Nome: Introduza um nome descritivo para a sua candidatura 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 browser, móveis), desmarque Gerar um segredo do cliente. Para clientes confidenciais (do lado do servidor), mantenha-o registado.
   • Âmbitos: Configure os escopos da API (ver Configurar escopos OAuth abaixo)
   • Expiração do token: Definir o acesso e tempos de atualização adequados ao token

CLI

Crie uma aplicação Databricks OAuth usando a CLI 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> pelo URL real de redirecionamento do seu cliente.

Configurar âmbitos OAuth

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

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

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

Configurar acesso à rede (opcional)

Se o seu espaço de trabalho Databricks tiver restrições de acesso ao IP, adicione os endereços IP de saída do seu cliente à lista de permissões do espaço de trabalho. Caso contrário, o espaço de trabalho bloqueia pedidos de autenticação do seu cliente. Consulte Gerenciar listas de acesso IP.

Configure o seu cliente

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

Exemplos OAuth

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

Inspetor MCP

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

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

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

Configurar o MCP Inspector:

1. Executa o inspetor: npx @modelcontextprotocol/inspector.
2. Defina o Tipo de Transporte para Streamable HTTP.
3. Introduza o URL do seu servidor MCP Databricks.
4. Na secção de Autenticação , adicione o seu ID de cliente OAuth.
5. Clique em Abrir Definições de Autenticação e escolha Guided ou Quick flow.
6. Após a autenticação bem-sucedida, cole o token de acesso no Bearer Token na secção Autenticação de Token de API.
7. Clique em Conectar.

Conectores Claude

Ligue o Claude a servidores MCP geridos e externos do Databricks usando Claude Connectors com MCP remoto.

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

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

Configurar Claude:

1. Ir a Definições >de Conectores no Claude.
2. Clique em Adicionar conector personalizado.
3. Introduza o URL do seu servidor MCP Databricks.
4. Introduza o ID de cliente da sua aplicação OAuth.
5. Clique em Adicionar para concluir.

Cursor/Windsurf

Para ligar de forma segura um IDE local como Cursor ou Windsurf a um servidor MCP Databricks, use mcp-remote com OAuth. Siga as instruções do repositório mcp-remote para configurar o mcp-remote. Depois segue a configuração de autenticação OAuth para garantir que o teu OAuth está configurado corretamente.

Configurar Cursor ou Windsurf:

1. Localize o seu ficheiro de configuração MCP:

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

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

   Para clientes confidenciais OAuth (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 públicos OAuth (sem client secret):

   {
     "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 de host do seu espaço de trabalho Databricks.

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

Ligue clientes usando autenticação por token de acesso pessoal (PAT)

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

1. Gera um token de acesso pessoal no teu espaço de trabalho Databricks. Consulte Autentique-se com tokens de acesso pessoal do Azure Databricks (legado).

2. Configurar o acesso à rede (opcional).

   Se o seu espaço de trabalho Databricks tiver restrições de acesso 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 implementação para obter os endereços IP necessários.

3. Configure o seu cliente.

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

Exemplos de PAT

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

Cursor

O cursor suporta MCP através da sua configuração de definições.

1. Abre as definições do cursor.

2. Adicione a seguinte configuração (adapte o 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 de host do seu espaço de trabalho Databricks.

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

Claude Desktop

O Claude Desktop pode ligar-se aos servidores MCP da Databricks usando mcp-remote.

1. Encontre o seu claude_desktop_config.json ficheiro:

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

2. Adicione a seguinte configuração (adapte o 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 de host do seu espaço de trabalho Databricks.

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

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

Replit

O Replit suporta a ligação a servidores MCP Databricks através de configuração personalizada de servidores MCP.

1. No seu espaço de trabalho Replit, clique em Adicionar Servidor MCP.

2. Introduza a URL do seu servidor MCP 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.

Limitações

• Registro dinâmico de cliente: o Databricks não suporta fluxos OAuth de registro de cliente dinâmico 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 a token de acesso pessoal do servidor MCP personalizado: Servidores MCP personalizados hospedados em Databricks Apps não oferecem suporte a tokens de acesso pessoal para autenticação.
• Autorização em nome do usuário: os servidores MCP personalizados hospedados em aplicativos Databricks não oferecem suporte à autorização em nome do usuário.

Próximos passos

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