Conectar Claude Code

Use o Claude Code ou o aplicativo desktop Claude com modelos, ferramentas MCP e habilidades via Unity Gateway. Para o Claude Code, use a CLI do Gateway Unity (ug) ou configure a conexão manualmente. Para o app desktop, configure a conexão nas configurações do app.

Para conectar ferramentas a uma configuração existente do Claude Code, acesse Adicionar ferramentas MCP. Para Claude na web ou em uma sessão de desktop usando sua conta Claude, use Claude connectors.

Prerequisites

Você precisa da URL do seu workspace do Azure Databricks e do acesso aos modelos que deseja usar. Para configuração desktop, instale o aplicativo desktop mais recente da Claude e peça ao administrador da conta um ID de cliente OAuth, conforme descrito abaixo.

Se seu administrador já configurou seu dispositivo, siga as instruções de login e lançamento da sua organização.

Código Claude

Use a CLI do Unity Gateway (recomendada)

Instale ug, então execute este comando a partir do diretório do seu projeto:

ug claude

Siga as instruções para selecionar seu espaço de trabalho e fazer login. ug configura a conexão e abre o Claude Code no seu terminal. Comece a trabalhar com os mesmos prompts e comandos que você já usa. Para mudar de modelo, insira /model.

Continue para Adicionar ferramentas MCP para conectar dados e serviços. Para baixar habilidades compartilhadas, execute ug skills add e selecione as habilidades que você quer. Veja Adicionar ferramentas e habilidades para mais opções.

Configure o Código Claude manualmente

Mescle as seguintes configurações a ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_MODEL": "<model-api-name>",
    "ANTHROPIC_BASE_URL": "https://<workspace-hostname>/ai-gateway/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<databricks-personal-access-token>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
    "CLAUDE_CODE_USE_GATEWAY": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Substitua <workspace-hostname> pelo nome do seu espaço de trabalho, sem https://. Defina <model-api-name> para o nome completo do Unity Catalog de uma API de modelo Claude que você possa acessar, e forneça seu token de acesso pessoal do Azure Databricks.

Execute claude a partir do diretório do seu projeto. Para outras configurações, veja Configurações do Claude Code.

Adicionar ferramentas MCP

Para usar system.ai.dbsql, system.ai.sandbox, ou system.ai.web_search, um administrador de conta deve ativar a versão beta do Unity Gateway a partir da página de Pré-visualizações do console da conta. Veja Gerenciar visualizações da conta.

1. Abra os MCPs do Unity Gateway > no seu espaço de trabalho. Escolha um MCP embutido ou registre seu servidor MCP externo.

2. Copie o nome completo do MCP, como system.ai.github ou <catalog>.<schema>.<service>.

3. Confirme que você tem acesso ao MCP.

4. Após a instalação ug, adicione o MCP ao Claude Code:

   ug mcp add --agents claude --names <catalog>.<schema>.<service>
   

   Substitua o marcador pelo nome que você copiou. Por exemplo, use --names system.ai.github para o GitHub. Para escolher serviços de forma interativa, omita --names.

Na primeira configuração, siga as instruções para selecionar seu espaço de trabalho, fazer login e escolher um modelo. ug configura tanto o acesso ao modelo quanto ao MCP e atualiza as credenciais. Reinicie o Claude Code com ug claude, então teste uma ferramenta.

Adicionar ferramentas MCP manualmente

Use o cliente OAuth integrado abaixo ou configure seu próprio aplicativo OAuth. Para adicionar um MCP com o cliente embutido, execute:

claude mcp add --transport http --scope user \
  --client-id claude-code --callback-port 3118 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>"

Substitua o nome do host e o nome do MCP. Isso usa o cliente OAuth embutido claude-code . Abra o Claude Code, insira /mcp, e faça login no servidor com sua conta Azure Databricks. Repita com um nome diferente de servidor para cada MCP que você quiser adicionar, depois teste uma ferramenta.

Teste uma ferramenta MCP

1. No Claude Code, insira /mcp e verifique se o servidor está conectado.
2. Peça para Claude listar as ferramentas desse servidor e depois solicite uma operação de leitura. Para o GitHub, peça para ele encontrar uma issue em um repositório que você possa acessar. Para um servidor personalizado, use uma ferramenta e entradas que você testou durante o registro.
3. Se uma chamada de ferramenta pedir que você faça login, abra o link de login devolvido pelo MCP, complete o consentimento do provedor e então tente a chamada novamente.
4. Verifique se Claude faz uma chamada de ferramenta e retorna o resultado. Uma resposta em texto sozinha não verifica a conexão.

Para usar dados do Azure Databricks, conecte-se system.ai.genie_one_mcp para perguntas comerciais ou system.ai.dbsql para SQL. Por exemplo, peça para o MCP SQL executar SELECT 1 AS result.

Para permissões, políticas e uso, consulte Gerenciar um MCP.

Conecte habilidades manualmente

Para expor as habilidades publicadas do Unity Gateway como ferramentas, registre o registro de habilidades como um servidor HTTP MCP:

claude mcp add --transport http --scope user \
  --header "Authorization: Bearer <databricks-personal-access-token>" \
  databricks-skill-registry \
  "https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>"

Substitua os marcadores de lugar pelo seu workspace, token e esquema de habilidades. Mantenha a barra final antes de ?schema. Para incluir múltiplos esquemas, repita o parâmetro: ?schema=main.default&schema=ml.prod.

Reinicie o Claude Code e verifique a conexão com /mcp. Peça ao Claude para usar uma habilidade pelo nome completo, como Use <catalog>.<schema>.<skill-name> to review this query.. Esta conexão expõe habilidades como ferramentas MCP; ug skills add baixa habilidades para descoberta nativa, por outro lado.

Aplicativo de desktop do Claude

1. Obtenha um ID de cliente OAuth

Peça ao administrador da sua conta para criar uma conexão de aplicação OAuth. No console de contas do Azure Databricks, abra Configurações > Conexões > do aplicativo Adicionar conexão e uso:

Salve a conexão e copie o ID do Cliente. Se você planeja conectar habilidades, registre também http://127.0.0.1:53280/callback.

2. Conectar-se ao Unity Gateway

Na tela de login do aplicativo para desktop, selecione Ajuda > Solução de problemas > Ativar modo de desenvolvedor e, em seguida, Desenvolvedor > Configurar inferência de terceiros.

Na página de Conexão , selecione Gateway e insira:

Substitua <workspace-hostname> pelo seu nome de host do workspace do Azure Databricks. Deixe as outras configurações no padrão. Veja a configuração do gateway da Anthropic para ver os detalhes dos campos.

Clique em Testar conexão e faça login no Azure Databricks. Selecione Aplicar Mudanças, depois Salvar e Reiniciar. Na tela de login, escolha a configuração de terceiros e inicie uma conversa no Code ou no Cowork.

3. Adicionar ferramentas e habilidades MCP

Abra Desenvolvedor > Configurar conectores de inferência de terceiros >. Em Servidores MCP Gerenciados, adicione uma entrada para cada MCP ou registro de habilidades que você deseja usar.

Use estas configurações para ambos os tipos de conector:

Para um MCP, encontre seu nome de três partes em Unity Gateway > MCPs no seu espaço de trabalho. Dê ao conector um nome descritivo, defina a porta de retorno de chamada para 53180, e use esta URL:

https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>

Para competências, dê um nome ao conector databricks-skill-registry, defina a porta de callback como 53280 e use:

https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>

Mantenha a barra final antes de ?schema. Para incluir múltiplos esquemas, repita o parâmetro: ?schema=main.default&schema=ml.prod. Essas habilidades são expostas a Claude como ferramentas através do conector.

Para cada conector, clique em Login & testar e complete o login. Selecione Aplicar Mudanças, depois Salvar e Reiniciar. Peça ao Claude para usar uma ferramenta conectada ou uma habilidade usando o nome completo. Veja Adicionar ferramentas e habilidades para requisitos de acesso e mais opções.

Conectores do Claude

Para system.ai.dbsql, primeiro ative a versão beta do Unity Gateway.

Use conector personalizado para adicionar ferramentas MCP do Azure Databricks ao Claude na web ou no desktop usando sua conta Claude.

1. Peça para um administrador de conta criar um cliente OAuth. Para um MCP, selecione o ai-gateway escopo e registre ambas as URLs de redirecionamento:

   • https://claude.ai/api/mcp/auth_callback
   • https://claude.com/api/mcp/auth_callback

2. No Claude, abra Configurações > Conectores > Adicionar conector personalizado.

3. Insira a URL do MCP:

   https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>
   

4. Insira o ID do cliente OAuth e, para um cliente confidencial, seu segredo. Clique em Adicionar e complete o login.

5. Em uma conversa, ative o conector e peça ao Claude para chamar uma de suas ferramentas. Para system.ai.dbsql, tente SELECT 1 AS result.

Se seu espaço de trabalho restringe IPs de entrada, permita os IPs de saída do Claude. Consulte Autenticação e rede do MCP para permissões, login do provedor e solução de problemas.

{
  "mcpServers": {
    "databricks-tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>",
        "--header",
        "Authorization: Bearer <databricks-pat>"
      ]
    }
  }
}

Solução de problemas

• Claude Code não se conecta: Execute ug doctor se você usar ug. Para configuração manual, verifique o hostname do seu workspace, o token, o nome do modelo e as permissões do modelo.

• Falha no login da área de trabalho: Verifique o ID do cliente, /oidc emissor e ai-gateway escopo. A URL de redirecionamento registrada deve corresponder ao host e porta do conector: 53180 para modelos e MCPs, ou 53280 para habilidades neste guia. As alterações na aplicação do OAuth podem levar até 30 minutos para entrar em vigor.

• Um modelo de desktop está faltando: Verifique suas permissões de modelo. Em Conexão > Modelos > Lista de modelos, adicione o nome completo do modelo no Unity Catalog. Uma lista explícita substitui a descoberta automática, então inclua todos os modelos que você quer usar. Aplique as mudanças e reinicie.

• Um MCP ou conector de habilidades falha: Verifique sua URL e permissões. O campo do servidor de autorização deve conter o array JSON mostrado acima. Clique em Entrar e testar para inspecionar o erro.

• O login do workspace funciona, mas uma ferramenta pede para você fazer login: Abra o link de login devolvido pelo MCP, faça login com o provedor externo e então tente a chamada novamente. O login no espaço de trabalho e o login do provedor são etapas separadas.

• Claude Code OAuth relata um descompasso de redirecionamento ou a conexão expira: Para um app OAuth personalizado, compare a URL de redirecionamento com o host e a porta de retorno e verifique o acesso à rede. As alterações no app OAuth podem levar até 30 minutos para entrar em vigor.

Próximas Etapas 

• Referência ao CLI do ug
• Adicionar ferramentas e habilidades