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.

Antes de começar

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

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.

Para adicionar ferramentas ou habilidades MCP, execute esses comandos no seu terminal e depois reinicie o Claude Code:

ug mcp add
ug skills add

Cada comando permite que você escolha o que adicionar. Veja Adicionar ferramentas e habilidades para mais detalhes.

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 manualmente

Encontre o nome de três partes do serviço MCP em Unity Gateway > MCPs em seu workspace e registre-o com Claude Code:

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 serviço. Abra o Claude Code, insira /mcp, e asimile o servidor com sua conta Azure Databricks. Repita com um nome diferente de servidor para cada serviço que você quiser adicionar.

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:

Setting Valor
Tipo de identidade Aplicação padrão
Nome do aplicativo claude-desktop
Gerar um segredo de cliente Desmarcado (cliente público)
URL de redirecionamento http://127.0.0.1:53180/callback
Escopos de acesso ai-gateway

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:

Setting Valor
Tipo de credencial Login interativo
Gateway base URL https://<workspace-hostname>/ai-gateway/anthropic
ID do cliente Seu ID de cliente OAuth
URL do emissor https://<workspace-hostname>/oidc
Token de portador Token de acesso
Scopes ai-gateway
Adicionar offline_access habilitado
Porta de redirecionamento 53180

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 serviço MCP ou registro de habilidades que você deseja usar.

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

Setting Valor
Transport HTTP transmissível
OAuth Traga seu próprio cliente
ID do cliente Seu ID de cliente OAuth
Segredo do cliente Deixar em branco
Servidor de autorização ["https://<workspace-hostname>/oidc"]
Scope ai-gateway
Solicitação offline_access habilitado
Host de retorno de chamada 127.0.0.1

Para um serviço 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.

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 serviços MCP, 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.

Próximas Etapas 

  • Last updated on