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

Conecte clientes não Databricks aos servidores MCP Databricks

info

Beta

Este recurso está em fase beta.

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

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

  • Acesse as funções, tabelas e índices vetoriais do Unity Catalog em seu assistente de IDE ou AI
  • Consulte dados do Databricks diretamente do Claude, Cursor, Replit ou outras ferramentas compatíveis com MCP.

Pré-requisitos​

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

  • acesso ao recurso : verifique se sua account tem acesso ao recurso Unity Catalog que você deseja usar

  • Acesso à rede : Se o site workspace tiver restrições de IP, permita listar os endereços IP de seus clientes

Métodos de autenticação​

Escolha o método de autenticação mais adequado aos seus requisitos de segurança:

Método

gerenciar/MCP externo

MCP personalizado

Nível de segurança

Melhor para

OAuth

Suportado

Suportado

Alta - permissões com escopo, tokens automáticos refresh

Uso de 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, testes, acesso de curto prazo

Conecte clientes usando autenticação OAuth​

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

nota

Os servidores MCP do Databricks suportam ambos os tipos de clientes, de acordo com a especificação de autorização MCP:

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

Obtenha o URL de redirecionamento OAuth do seu cliente.​

Cada cliente MCP requer URLs de redirecionamento OAuth específicos para os retornos de chamada de autenticação. Os padrões comuns de URLs 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

Consulte a documentação do seu cliente para encontrar os URLs de redirecionamento exatos necessários.

Crie o aplicativo OAuth do Databricks.​

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

Crie um aplicativo OAuth Databricks usando o consoleaccount:

  1. No console account Databricks , acesse Configurações > Conexões de aplicativos > Adicionar 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 : Adicione os URLs de redirecionamento exigidos pelo seu cliente externo.
    • Tipo de cliente : Para clientes públicos (baseados em navegador, dispositivos móveis), desmarque a opção Gerar um segredo do cliente . Para clientes confidenciais (lado do servidor), mantenha essa opção marcada.
    • Escopos : Configure os escopos da API (consulte Configurar escopos OAuth abaixo)
    • Expiração dos tokens : Defina os tempos de acesso e refresh adequados para os tokens.

Configurar escopos OAuth​

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

Tipo de servidor MCP

Escopo(s) necessário(s)

Genie spaces

mcp.genie

Funções Unity Catalog do MCP

mcp.functions

Busca vetorial MCP

mcp.vectorsearch

MCP Databricks SQL

mcp.sql, sql.warehouses, sql.statement-execution

funções externas do MCP

mcp.external

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

Configurar 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 permissões workspace . Caso contrário, o workspace bloqueará as solicitações de autenticação do seu cliente. Veja gerenciar listas de acesso IP.

Configure seu cliente​

Após criar o aplicativo OAuth no Databricks, configure seu cliente MCP específico com as credenciais OAuth. Cada cliente possui seu próprio método de configuração. Consulte os exemplos específicos da plataforma a seguir para obter instruções detalhadas sobre os clientes MCP mais 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.

O MCP Inspector é uma ferramenta de desenvolvimento para teste e depuração de servidores MCP.

Inspetor MCP

Siga as instruções de 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 de cliente )

Configurar o MCP Inspector:

  1. execução do inspetor: npx @modelcontextprotocol/inspector.
  2. Defina o tipo de transporte como Streamable HTTP.
  3. Insira o URL do seu servidor Databricks MCP.
  4. Na seção Autenticação , adicione seu ID de cliente OAuth.
  5. Clique em Abrir configurações de autenticação e escolha Fluxo guiado ou Fluxo rápido .
  6. Após a autenticação bem-sucedida, cole o access token em Tokens Bearer na seção Autenticação de tokensAPI .
  7. Clique em Conectar .

Fluxo de autenticação do MCP Inspector

Conecte clientes usando autenticação access token pessoal (PAT).​

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

nota

access tokens pessoal são suportados apenas para servidores gerenciados e servidores MCP externos. Servidores MCP personalizados exigem autenticação OAuth.

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

  2. Configurar 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 permissões. Consulte a documentação do seu cliente ou a configuração de rede do 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 possui seu próprio método de configuração. Consulte os exemplos específicos da plataforma abaixo para obter instruções detalhadas sobre os clientes MCP mais populares.

Exemplos de PAT​

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

  1. Abra as configurações do cursor.

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

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

Limitações​

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

Próximos passos​