Ligue MCPs a assistentes de IA e agentes de codificação

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

Ao ligar clientes aos MCPs do Databricks, pode:

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

Como funciona

Todos os clientes ligam-se aos MCPs do Databricks da mesma forma: adicionam o URL do servidor à configuração MCP do cliente, autenticam-se com OAuth ou um token de acesso pessoal, e o cliente chama ferramentas via HTTP Streamable. O URL determina a que MCP acede: um servidor MCP gerido para dados e ferramentas do Unity Catalog, um Serviço MCP para ferramentas externas, ou o seu próprio servidor MCP alojado no Databricks:

Requisitos

• URLs do servidor: Obtenha os URLs de servidor apropriados para o servidor MCP da Databricks que pretende usar:
  • Servidores MCP geridos para dados e código do Azure Databricks
  • Serviços MCP para aplicações de terceiros como Slack, GitHub e Google Drive
  • Servidores MCP alojados em Databricks para o seu próprio servidor MCP nas aplicações Databricks
• Acesso a recursos: Verifique se tem acesso aos servidores MCP que pretende usar e a quaisquer recursos subjacentes. Por exemplo, se usares o servidor MCP gerido pelo Genie, precisas de acesso ao Agente Genie subjacente.
• Acesso à rede: 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 para permitir que este se ligue ao seu espaço de trabalho:
  • Siga a documentação para listas de acesso IP de espaço de trabalho e listas de acesso IP de contas para verificar se tem alguma restrição
  • Se as listas de acesso IP estiverem ativadas, identifique os IPs de saída do seu cliente. Esta informação está geralmente disponível na documentação do cliente; por exemplo, o Claude documenta aqui os seus endereços IP de saída.
  • Certifique-se de que os IPs de saída do seu cliente são adicionados à lista.

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. Defina as configurações do aplicativo:
   • 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.
   • Escopos: Configure os escopos da API (veja a referência de escopos do Databricks OAuth para os escopos disponíveis)
   • 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
  }
}'

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

{
  "client_id": "<your-client-id>",
  "client_secret": "",
  "integration_id": "<your-integration-id>"
}

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 aos servidores MCP geridos pela Databricks e aos Serviços MCP usando conectores Claude 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 (e o segredo de cliente se a ligação da sua aplicação OAuth Databricks for um cliente confidencial).
5. Clique em Adicionar para concluir.

Código Claude

A forma mais rápida de ligar o Claude Code é com ucode, que autentica através do login da CLI Databricks — sem necessidade de aplicação OAuth, ID de cliente ou segredo do cliente:

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents claude --services <catalog>.<schema>.<service>
ucode claude

Substitua <catalog>.<schema>.<service> pelo nome totalmente qualificado do Serviço MCP. Consulte Integrar com agentes de codificação para mais detalhes.

OpenAI Codex

Ligue o Codex OpenAI aos servidores MCP Databricks com ucode, que autentica através do login CLI Databricks — sem necessidade de aplicação OAuth, ID de cliente ou segredo de cliente:

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents codex --services <catalog>.<schema>.<service>
ucode codex

Substitua <catalog>.<schema>.<service> pelo nome totalmente qualificado do Serviço MCP. ucode escreve o servidor MCP na configuração do teu Codex e atualiza automaticamente o token OAuth. Consulte Integrar com agentes de codificação para mais detalhes.

Aplicações ChatGPT

Ligue o ChatGPT aos servidores MCP geridos pela Databricks e aos Serviços MCP usando aplicações ChatGPT personalizadas com Modo Desenvolvedor e aplicações MCP completas.

Adicionar aplicações personalizadas do ChatGPT exige:

• Modo Desenvolvedor ativado
• Um espaço de trabalho ChatGPT Empresarial, para Negócios ou Educação

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

• URL de redirecionamento: https://chatgpt.com/connector_platform_oauth_redirect
• Lista de permissão de IP: Adicionar endereços IP de saída do ChatGPT

Configurar o ChatGPT:

1. No ChatGPT, vai a Definições>Apps>Criar App.
2. Introduza o URL do seu servidor MCP Databricks.
3. Use o OAuth como método de autenticação.
4. Introduza o ID do cliente e o segredo da sua aplicação OAuth (se aplicável).
5. Complete a configuração e guarde a sua aplicação.

Cursor/Windsurf

Para ligar um IDE local como Cursor ou Windsurf a um servidor MCP Databricks, adicione o seu servidor MCP ao ficheiro de configuração MCP.

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

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

2. Adicione uma das seguintes configurações. Para Cursor, ucode é a opção mais simples. Caso contrário, use a opção OAuth que corresponda ao tipo de cliente.

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents cursor --services <catalog>.<schema>.<service>
ucode cursor

{
  "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\" }"
      ]
    }
  }
}

{
  "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\" }"
      ]
    }
  }
}

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.

Para os Serviços MCP, gera um token de acesso pessoal e passa-o como token portador no Authorization cabeçalho.

Use este token para testes locais e escolha a vida útil mais curta que se adapte ao seu fluxo de trabalho. Não comprometas tokens no controlo de versões nem os partilhes em ficheiros de configuração do cliente. Para ligações de clientes de produção ou utilizadas por toda a equipa, use OAuth em vez de um PAT. Para agentes de codificação (Claude Code, Cursor, OpenAI Codex e outros), ucode é a opção mais simples — autentica através do login da CLI Databricks e atualiza automaticamente o token.

1. Gera um token de acesso pessoal no teu espaço de trabalho Databricks. Consulte Autenticar com tokens de acesso pessoal do Azure Databricks (legacy).

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.

   Quando um cliente pedir cabeçalhos personalizados, passe o token como token portador no Authorization cabeçalho: Authorization: Bearer <YOUR_TOKEN>.

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.

Resolver problemas de ligação

Siga estes passos de resolução de problemas para diagnosticar e resolver problemas comuns de ligação.

Validar autenticação

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

OAuth utilizador-para-máquina (U2M)

Para autenticação utilizador-máquina (U2M) OAuth, teste a ligação com o MCP Inspector. O fluxo OAuth valida as credenciais durante o processo de ligação.

Diretor de serviço (M2M)

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

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

Este comando valida a configuração do seu principal de serviço e apresenta informações sobre a identidade autenticada. Se o comando devolver um erro, reveja a configuração do seu principal de serviço e certifique-se:

• O principal do serviço foi criado na sua conta Databricks
• O ID do cliente e o segredo do cliente estão corretamente configurados
• O principal do serviço tem as permissões adequadas para aceder aos recursos necessários

Verificar a configuração da rede

As restrições de rede podem impedir que clientes externos se liguem ao seu espaço de trabalho Databricks. Certifique-se de que quaisquer políticas de lista de acesso IP do Databricks estão configuradas para permitir que o seu cliente se ligue à sua conta e espaço de trabalho Databricks. Consulte Requisitos.

Identificar problemas de ligação específicos do cliente

Tenta ligar-te a outro cliente MCP para ver se o problema persiste. A Databricks recomenda testar com o MCP Inspector. Se a tua ligação funciona com o MCP inspector mas falha com o teu cliente, o problema provavelmente está na configuração do teu cliente. Contacte o prestador cliente para mais apoio.

Reporte problemas ao suporte da Databricks

Se continuar a ter problemas de ligação após completar estes passos de resolução de problemas:

1. Revise os registos do seu cliente MCP, como Claude, Cursor ou MCP Inspector, para mensagens de erro e rastreios 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 da rede (restrições de IP, regras de firewall)

3. Contacte o suporte e partilhe a informação de diagnóstico para resolver o problema.

Limitações

• Registo dinâmico de clientes: O Databricks não suporta fluxos OAuth de registo dinâmico de clientes para servidores MCP geridos, Serviços MCP ou servidores MCP alojados no Databricks. Clientes externos e IDEs que exigem o Registro Dinâmico de Cliente não são suportados usando a autenticação OAuth.
• Suporte para tokens de acesso pessoais em servidores MCP alojados no Databricks: Os servidores MCP que aloja no Databricks Apps não suportam tokens de acesso pessoais para autenticação.

Recursos adicionais

• Use servidores MCP gerenciados para conectar agentes aos dados do Catálogo Unity
• Ligue agentes a ferramentas com os Serviços MCP para aceder a serviços de terceiros
• Aloja o teu próprio servidor MCP para ferramentas específicas da organização
• Competências de agente para assistentes de programação de IA para ensinar agentes de programação como Claude Code e Cursor Azure Databricks padrões de desenvolvimento