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

Conecte MCPs a assistentes de AI e agentes de codificação

nota

Os MCPs do Databricks aos quais você pode se conectar estão em diferentes estágios de lançamento. Consulte servidores MCP gerenciados, Serviços MCP e servidores MCP hospedados pela Databricks para o estágio atual de cada recurso.

Conecte clientes, assistentes de IA e IDEs que oferecem suporte ao Protocolo de Contexto do Modelo (MCP) aos MCPs do Databricks. Isso proporciona acesso aos dados e às ferramentas do Databricks diretamente em seu ambiente de desenvolvimento.

Ao conectar clientes a MCPs do Databricks, é possível:

  • Acesse funções, tabelas e índices vetoriais do Unity Catalog do seu IDE ou assistente de AI
  • Consulte dados do Databricks diretamente de Claude, Claude Code, Cursor, Replit ou outras ferramentas habilitadas para MCP

Como funciona​

Todo cliente se conecta aos MCPs do Databricks da mesma forma: adicione a URL do servidor à configuração de MCP do cliente, autentique-se com OAuth ou um access token pessoal, e o cliente chama as ferramentas via HTTP Transmissível. A URL determina qual MCP você acessa — um servidor MCP gerenciado para dados e ferramentas do Unity Catalog, um Serviço MCP para ferramentas externas, ou seu próprio servidor MCP hospedado pelo Databricks:

Um cliente MCP, como Claude, Claude Code, Cursor ou ChatGPT, é configurado com uma URL de servidor MCP do Databricks, autentica-se com OAuth ou um access token pessoal e chama ferramentas via HTTP Streamable em um de três tipos de endpoint: dados e código do Databricks por meio de servidores MCP gerenciados; ferramentas de terceiros como GitHub e Slack por meio de Serviços MCP; ou seu próprio servidor MCP hospedado em Databricks Apps.

Pré-requisitos​

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

  • Acesso aos recursos : Verifique se você tem acesso aos servidores MCP que deseja usar e a quaisquer recursos subjacentes. Por exemplo, se você usa o servidor MCP gerenciado pelo Genie, você precisa de acesso ao Genie Space subjacente.

  • Acesso à rede : se seu workspace Databricks tiver restrições de acesso por IP, adicione os endereços IP de saída do seu cliente à lista de permitidos 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 account para verificar se há alguma restrição em vigor.
    • Se as listas de acesso IP estiverem habilitadas, identifique os IPs de saída do seu cliente. Esta informação geralmente está disponível na documentação do cliente; por exemplo, Claude documenta seus endereços IP de saída aqui.
    • Certifique-se de que os IPs 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

Servidores MCP gerenciados e Serviços MCP

Servidor MCP hospedado pela Databricks

Nível de segurança

Melhor para

OAuth (recomendado)

Suportado

Suportado

Permissões de alto escopo, refresh automático de tokens

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

Tokens de acesso pessoal

Suportado

Não suportado

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

Desenvolvimento individual, teste, acesso de curto prazo

Conectar clientes usando a autenticação OAuth​

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

nota

Os servidores MCP da Databricks oferecem suporte a ambos os tipos de cliente conforme a especificação de autorização do MCP:

  • Clientes públicos : Não é necessário segredo do cliente.
  • Clientes confidenciais : Inclua o segredo do cliente

Obtenha a URL de redirecionamento OAuth do seu cliente​

Cada cliente MCP requer URLs de redirecionamento OAuth específicas para retornos de chamada 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 de redirecionamento exatas necessárias.

Crie o aplicativo OAuth do Databricks​

Solicite a um administrador de conta que crie uma aplicação Databricks OAuth. Recupere seu ID de cliente e, se seu cliente exigir, o segredo do cliente.

Criar um aplicativo OAuth da Databricks usando o console da account:

  1. No console do account Databricks, vá para Configurações > Conexões de Aplicativos > Adicionar conexão .
  2. Configure 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, móveis), desmarque Gerar um segredo do cliente . Para clientes confidenciais (lado do servidor), mantenha-o selecionado.
    • Escopos : Configure os escopos da API (consulte a referência de escopos do OAuth do Databricks para escopos disponíveis)
    • Expiração do token : Defina os tempos apropriados de acesso e refresh dos tokens

Configurar acesso à rede (opcional)​

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

Configure seu cliente​

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

Exemplos de OAuth​

Os exemplos a seguir mostram como configurar clientes MCP específicos com autenticação OAuth. Primeiro, siga 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 desenvolvedor para testes e depuração de servidores MCP.

MCP Inspector

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

  • Redirecionar URLs :

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

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

Configurar MCP Inspector:

  1. Execute o inspetor: npx @modelcontextprotocol/inspector.
  2. Defina Transport Type como Streamable HTTP.
  3. Insira a URL do seu servidor MCP do Databricks.
  4. Na seção Autenticação , adicione seu ID de cliente OAuth.
  5. Clique em Abrir configurações de autenticação e escolha o fluxo Guiado ou Rápido .
  6. Após autenticação bem-sucedida, cole o access token em Bearer Token na seção Autenticação de Token da API .
  7. Clique em Conectar .

Fluxo de Autenticação do MCP Inspector

Conectar clientes usando autenticação de access token pessoal (PAT)​

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

nota

Tokens de access token pessoal são suportados apenas para servidores MCP gerenciados e serviços MCP. Servidores MCP hospedados no Databricks exigem autenticação OAuth.

Para serviços MCP, gere um tokens na página de detalhes do serviço:

  1. No seu workspace, abra o MCP Service no Catalog Explorer ou vá para AI Gateway > MCPs e selecione o serviço.
  2. Em Começar , clique em Gerar Access Token .
  3. Copie o comando export DATABRICKS_TOKEN=... gerado no seu terminal. Os tokens também são adicionados aos exemplos de solicitação na página.

Use este token para teste local e escolha a vida útil mais curta que se adapta ao seu fluxo de trabalho. Não faça commit de tokens no controle de versão nem os compartilhe em arquivos de configuração do cliente. Para conexões de cliente de produção ou de toda a equipe, use OAuth em vez de um PAT.

  1. Gere um access token pessoal em seu workspace do Databricks. Consulte Autenticar com access token pessoais do Databricks (legado).

  2. Configure o acesso à rede (opcional).

    Se seu workspace Databricks tiver restrições de acesso por IP, adicione os endereços IP de saída de seu cliente à lista de permitidos. Consulte a documentação de seu cliente ou a configuração de rede de 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 tem seu próprio método de configuração. Consulte os exemplos específicos da plataforma abaixo para obter instruções detalhadas para clientes MCP populares.

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

Exemplos de PAT​

Os exemplos a seguir mostram como configurar clientes MCP específicos com autenticação por 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 por meio de sua configuração de configurações.

  1. Abra suas configurações do Cursor.

  2. Adicione a seguinte configuração (adapte o URL para o seu 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 do Databricks.

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

Solucionar problemas de conexão​

Siga os passos de solução de problemas para diagnosticar e resolver problemas de conexão comuns.

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.

Verificar a configuração de rede​

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

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

Tente conectar-se com um cliente MCP diferente para ver se o problema persiste. A Databricks recomenda testar com o Inspetor MCP. Se a conexão funcionar com o inspetor MCP, mas falhar com seu cliente, o problema provavelmente estará na configuração do cliente. Entre em contato com o provedor de cliente para obter mais suporte.

Relatar problemas ao suporte da Databricks​

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

  1. Revise os logs do seu cliente MCP, como Claude, Cursor ou MCP Inspector, para 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 de 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​

Recursos adicionais​

Nesta página