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

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

nota

Os MCPs da 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 na Databricks para o estágio atual de cada recurso.

Conecte clientes, assistentes de AI e IDEs que oferecem suporte ao Model Context Protocol (MCP) aos MCPs do Databricks. Isso fornece acesso aos dados e ferramentas do Databricks diretamente no seu ambiente de desenvolvimento.

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

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

Como funciona​

Cada cliente se conecta aos MCPs do Databricks da mesma maneira: 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 no 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 Streamable HTTP em um dos 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.

Requisitos​

  • URLs do servidor : obtenha as URLs de servidor apropriadas para o servidor MCP do Databricks que você deseja usar:

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

  • Acesso à rede : se o seu workspace do 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 você tem alguma restrição em vigor
    • Se as listas de acesso IP estiverem habilitadas, identifique os IPs de saída do seu cliente. Essas informações geralmente estão disponíveis na documentação do cliente; por exemplo, o 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 atende 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

Alto - permissões com 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 tokens com expiração

Desenvolvimento individual, teste, acesso de curto prazo

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

Alto - permissões com 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 tokens com expiração

Desenvolvimento individual, teste, acesso de curto prazo

Conectar clientes usando autenticação OAuth​

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

nota

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

  • Clientes públicos : Nenhum segredo de cliente é necessário
  • Clientes confidenciais : Incluir segredo do cliente

Obtenha a URL de redirecionamento OAuth do seu cliente​

Cada cliente MCP requer URLs de redirecionamento de OAuth específicas 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 os URLs de redirecionamento exatos necessários.

Criar o aplicativo Databricks OAuth​

Peça a um administrador de account que crie um aplicativo Databricks OAuth. Recupere seu ID do cliente e, se o seu cliente exigir, o segredo do cliente.

Crie uma aplicação OAuth do Databricks usando o console da account:

  1. No console de account do Databricks, vá para Settings > App Connections > Add connection .
  2. Configure as definiçõ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 de cliente . Para clientes confidenciais (lado do servidor), mantenha-o marcado.
    • Escopos : Configure os escopos da API (consulte a referência de escopos OAuth do Databricks para ver os escopos disponíveis)
    • Expiração de token : Defina os tempos apropriados de acesso e refresh do token

Configurar acesso à rede (opcional)​

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

Configurar seu cliente​

Após 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 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 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. [[ ## completed ##]]

dica

Para agentes de codificação (Claude Code, Cursor, OpenAI Codex e outros), ucode é a maneira mais rápida de conectar. Ele autentica por meio do seu login na CLI do Databricks e configura o agente e seus servidores MCP em um único comando, para que você não precise criar um aplicativo OAuth do Databricks ou gerenciar um ID de cliente e segredo.

O MCP Inspector é uma ferramenta de desenvolvedor para testes e depuração de servidores MCP. [[ ## completed ##]]

Inspetor MCP

Siga a 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 Gerar um segredo do cliente )

Configurar o Inspetor MCP:

  1. Faça a execução do inspetor: npx @modelcontextprotocol/inspector.
  2. Defina Transport Type como Streamable HTTP.
  3. Insira o URL do seu servidor MCP do Databricks.
  4. Na seção Autenticação , adicione seu ID de cliente OAuth.
  5. Clique em Open Auth Settings e escolha o fluxo Guided ou Quick .
  6. Após a autenticação bem-sucedida, cole o access token em Bearer Token na seção API Token Authentication .
  7. Clique em Conectar .

Fluxo de autenticação do Inspetor MCP

Conectar clientes usando autenticação por access token pessoal (PAT) [[ ## completed ##]]​

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

nota

Os access tokens pessoais são suportados apenas para servidores MCP gerenciados e serviços MCP. Os servidores MCP hospedados no Databricks exigem autenticação OAuth.

Para serviços MCP, gere um personal access token e passe-o como um token do portador no cabeçalho Authorization.

Use este token para testes locais e escolha o tempo de vida mais curto que se adeque ao seu fluxo de trabalho. Não faça commit de tokens no controle de origem nem os compartilhe em arquivos de configuração do cliente. Para conexões de cliente em produção ou em toda a equipe, 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 — ela autentica por meio do seu login da CLI do Databricks e refresh o token automaticamente.

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

  2. Configure o 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 permitidos. 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 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. Veja os exemplos específicos da plataforma abaixo para obter instruções detalhadas para clientes MCP populares.

    Quando um cliente solicitar cabeçalhos personalizados, transmita o token como tokens do 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 a MCP por meio de sua configuração de definições.

  1. Abra suas configurações do Cursor.

  2. Adicione a seguinte configuração (adapte a 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 estes passos 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.

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 configuração de rede​

As restrições de rede podem impedir que clientes externos se conectem ao seu workspace do Databricks. Certifique-se de que quaisquer políticas de lista de acesso IP do Databricks estejam configuradas para permitir que seu cliente se conecte à sua account e ao seu workspace do Databricks. Consulte Requisitos.

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

Tente conectar com um cliente MCP diferente para ver se o problema persiste. A Databricks recomenda testar com o MCP Inspector. Se sua conexão funcionar com o MCP inspector, mas falhar com seu cliente, o problema provavelmente está na configuração do seu cliente. Entre em contato com o provedor do cliente para obter mais suporte.

Relate problemas ao suporte da Databricks​

Se os problemas de conexão persistirem após a conclusão destes passos de solução de problemas:

  1. Revise 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 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. Entre em contato com o suporte e compartilhe as informações de diagnóstico para resolver o problema.

Limitações​

  • Registro dinâmico de cliente : o Databricks não é compatível com fluxos OAuth de registro dinâmico de cliente para servidores MCP gerenciados, serviços MCP ou servidores MCP hospedados no Databricks. Clientes externos e IDEs que exigem o Registro Dinâmico de Cliente não são suportados usando autenticação OAuth.
  • Suporte a personal access token para servidores MCP hospedados no Databricks : os servidores MCP que você hospeda no Databricks Apps não oferecem suporte a personal access tokens para autenticação.

Outros recursos​

Nesta página