Conectar o Claude Code
Use o Claude Code ou o aplicativo de desktop do Claude com modelos, ferramentas MCP e habilidades por meio do Unity Gateway. Para o Claude Code, use a CLI do Unity Gateway (ug) ou configure a conexão manualmente. Para o aplicativo de desktop, configure a conexão nas configurações do aplicativo.
Antes de começar
Você precisa da URL do seu workspace do Databricks e acesso aos modelos que deseja usar. Para a configuração na área de trabalho, instale o aplicativo Claude para desktop mais recente e solicite ao administrador da sua account um ID de cliente OAuth, conforme descrito abaixo.
Se o seu administrador já tiver configurado o seu dispositivo, siga as instruções de início de sessão e inicialização da sua organização.
Claude Code
Use a CLI do Unity Gateway (recomendado)
Instale o ug e execute este comando a partir do diretório do seu projeto:
ug claude
Siga as instruções para selecionar seu workspace 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 alterar os modelos, digite /model.
Para adicionar ferramentas ou habilidades do MCP, execute estes comandos no seu terminal e reinicie o Claude Code:
ug mcp add
ug skills add
Cada comando permite selecionar o que adicionar. Consulte Adicionar ferramentas e habilidades para obter detalhes.
Configure o Claude Code manualmente
Faça o merge das seguintes configurações em ~/.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 hostname do seu workspace, sem https://. Defina <model-api-name> com o nome completo no Unity Catalog de uma API de modelo Claude que você possa acessar e forneça seu access token pessoal do Databricks.
Execute claude no diretório do seu projeto. Para outras configurações, consulte Configurações do Claude Code.
Adicionar ferramentas MCP manualmente
Encontre o nome de três partes do serviço MCP em Unity Gateway > MCPs no seu workspace e, em seguida, registre-o no 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 hostname e o nome do serviço. Abra o Claude Code, insira /mcp e autentique o servidor com sua account do Databricks. Repita com um nome de servidor diferente para cada serviço que você deseja adicionar.
Connect skills manually
Para expor as habilidades publicadas do Unity Gateway como ferramentas, registre o registro de habilidades como um servidor MCP HTTP:
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 espaços reservados pelo seu Workspace, tokens e esquema de habilidades. Mantenha a barra à direita antes de ?schema. Para incluir vários esquemas, repita o parâmetro: ?schema=main.default&schema=ml.prod.
Reinicie o Claude Code e verifique a conexão com /mcp. Peça para o Claude usar uma habilidade pelo nome completo, como Use <catalog>.<schema>.<skill-name> to review this query.. Essa conexão expõe habilidades como ferramentas de MCP; em vez disso, ug skills add faz o download de habilidades para descoberta nativa.
Aplicativo Claude Desktop
1. Obter uma ID de cliente OAuth
Peça ao administrador da sua conta para criar uma conexão de aplicativo OAuth. No console da conta do Databricks, abra Settings > App connections > Add connection e use:
Contexto | Valor |
|---|---|
Tipo de identidade | Aplicativo padrão |
Nome do aplicativo |
|
Gerar um segredo de cliente | Desmarcado (cliente público) |
URL de redirecionamento |
|
Escopos de acesso |
|
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 Help > Troubleshooting > Enable Developer Mode e, em seguida, Developer > Configure Third-Party Inference .
Na página Connection , selecione Gateway e insira:
Contexto | Valor |
|---|---|
Tipo de credencial | Entrada interativa |
URL base do gateway |
|
ID do cliente | Seu ID de cliente OAuth |
URL do emissor |
|
Bearer token | access token |
Escopos |
|
Acrescentar | Ativada |
Porta de redirecionamento |
|
Replace <workspace-hostname> with your Databricks workspace hostname. Deixe as outras configurações com seus valores default. Consulte configuração de gateway da Anthropic para obter detalhes sobre os campos.
Clique em Testar conexão e faça login no Databricks. Selecione Aplicar alterações e, em seguida, Salvar e reiniciar . Na tela de login, escolha a configuração de terceiros e inicie uma conversa em Code ou Cowork .
3. Adicionar ferramentas e habilidades MCP
Abra Developer > Configure Third-Party Inference > Connectors . Em Managed MCP servers , 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:
Contexto | Valor |
|---|---|
Transporte | HTTP streamable |
OAuth | Bring your own client |
ID do cliente | Seu ID de cliente OAuth |
Segredo do cliente | Deixe em branco |
Servidor de autorização |
|
Escopo |
|
Solicitado | Ativada |
Host de retorno de chamada |
|
Para um serviço MCP , localize seu nome de três partes em Unity Gateway > MCPs no seu workspace. Dê ao conector um nome descritivo, defina Callback port como 53180 e use este URL:
https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>
Para skills , nomeie o conector como databricks-skill-registry, defina Callback port como 53280 e use:
https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>
Mantenha a barra à direita antes de ?schema. Para incluir vários esquemas, repita o parâmetro: ?schema=main.default&schema=ml.prod. Essas habilidades são expostas ao Claude como ferramentas por meio do conector.
Para cada conector, clique em Iniciar sessão e testar e conclua o início de sessão. Selecione Aplicar alterações e, em seguida, Salvar e reiniciar . Peça ao Claude para usar uma ferramenta ou habilidade conectada pelo nome completo. Consulte Adicionar ferramentas e habilidades para obter informações sobre os requisitos de acesso e mais opções.
Solução de problemas
O Claude Code não conecta: execute o ug doctor se você usar o ug. Para a configuração manual, verifique o hostname do seu workspace, o token, o nome do modelo e as permissões do modelo.
A falha no início de sessão da área de trabalho: verifique o ID do cliente, o emissor /oidc e o escopo ai-gateway. O URL de redirecionamento registrado deve corresponder ao host e à porta do conector: 53180 para modelos e serviços MCP, ou 53280 para habilidades neste guia. As alterações do aplicativo OAuth podem levar até 30 minutos para entrarem em vigor.
Um modelo de desktop está ausente: verifique as permissões do seu modelo. Em Connection > Models > Model list , adicione o nome completo do modelo do Unity Catalog. Uma lista explícita substitui a descoberta automática; portanto, inclua todos os modelos que deseja usar. Aplique as alterações e reinicie.
Um conector de MCP ou habilidade falha: verifique sua URL e permissões. O campo Authorization server deve conter o array JSON mostrado acima. Clique em Sign in & test para inspecionar o erro.