Associar Claude Code

Use o Claude Code ou a aplicação de desktop Claude com modelos, ferramentas MCP e competências através do Unity Gateway. Para o Claude Code, use a CLI do Gateway Unity (ug) ou configure a ligação manualmente. Para a aplicação de ambiente de trabalho, configura a ligação nas definições da aplicação.

Para ligar ferramentas a uma configuração Claude Code existente, vá a Adicionar ferramentas MCP. Para Claude na web ou numa sessão de ambiente de trabalho usando a tua conta Claude, usa Claude connectors.

Prerequisites

Precisa do URL do seu espaço de trabalho do Azure Databricks e do acesso aos modelos que pretende usar. Para configuração de desktop, instale a aplicação desktop mais recente da Claude e peça ao administrador de conta um ID de cliente OAuth, conforme descrito abaixo.

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

Código Claude

Utilize a CLI do Unity Gateway (recomendada)

Instale ug, depois execute este comando a partir do diretório do seu projeto:

ug claude

Siga as instruções para selecionar o seu espaço de trabalho e iniciar sessão. ug configura a ligação e abre o Claude Code no teu terminal. Começa a trabalhar com os mesmos prompts e comandos que já usas. Para mudar de modelo, introduza /model.

Continuar a adicionar ferramentas MCP para ligar dados e serviços. Para descarregar competências partilhadas, executa ug skills add e seleciona as que queres. Consulte Adicionar ferramentas e competências para mais opções.

Configurar manualmente o Código Claude

Junte as seguintes definiçõ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 nome de anfitrião do seu espaço de trabalho, sem https://. Defina <model-api-name> para o nome completo no Unity Catalog de uma API de um modelo Claude a que tenha acesso e forneça o seu token de acesso pessoal do Azure Databricks.

Executa claude a partir do diretório do teu projeto. Para outras definições, veja definiçõ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 da consola da conta. Consulte Gerir pré-visualizações da conta.

Abra os MCPs do Unity Gateway > no seu espaço de trabalho. Escolha um MCP incorporado ou registe o seu servidor MCP externo.
Copie o nome completo do MCP, como system.ai.github ou <catalog>.<schema>.<service>.
Confirma que tens acesso ao MCP.
Após a instalação ug, adicione o MCP ao Claude Code:
```
ug mcp add --agents claude --names <catalog>.<schema>.<service>
```
Substitua o marcador de posição pelo nome que copiou. Por exemplo, use o --names system.ai.github GitHub. Para escolher serviços de forma interativa, omita --names.

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

Adicionar ferramentas MCP manualmente

Utilize o cliente OAuth incorporado abaixo, ou configure a sua própria aplicação OAuth. Para adicionar um MCP com o cliente incorporado, 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 MCP. Isto utiliza o cliente OAuth incorporado claude-code . Abre o Claude Code, insere /mcp, e inicia sessão no servidor com a tua conta Azure Databricks. Repita com um nome de servidor diferente para cada MCP que queira adicionar, depois teste uma ferramenta.

Usa a tua própria aplicação OAuth

Faça com que um administrador de conta abra Definições > Ligações da aplicação > Adicionar ligação na consola da conta.
Introduza um nome como claude-code-mcp, desmarque Gerar um segredo de cliente para um cliente público, defina o URL de redirecionamento para http://localhost:8080/callback, e selecione o ai-gateway âmbito. Guarda e copia o ID do Cliente. Veja Crie uma app OAuth.

Registe o MCP usando esse ID de cliente e a porta de callback correspondente:

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

Abra o Claude Code, introduza /mcp, e inicie sessão. Se a sua organização requer um cliente confidencial, adicione --client-secret ao comando e introduza o segredo quando solicitado.

Teste uma ferramenta MCP

No Claude Code, introduza /mcp e verifique se o servidor está ligado.
Pede ao Claude para listar as ferramentas desse servidor e depois solicita uma operação de leitura. No GitHub, pede-lhe que encontre uma issue num repositório ao qual possa aceder. Para um servidor personalizado, usa uma ferramenta e entradas que testaste durante o registo.
Se uma chamada de ferramenta lhe pedir para iniciar sessão, abra o link de login devolvido pelo MCP, complete o consentimento do fornecedor e depois tente novamente a chamada.
Verifica se o Claude faz uma chamada de ferramenta e devolve o resultado. Uma resposta de texto por si só não verifica a ligação.

Para usar Azure Databricks data, ligue-se a system.ai.genie_one_mcp para perguntas empresariais ou system.ai.dbsql para SQL. Por exemplo, peça ao SQL MCP para executar SELECT 1 AS result.

Para permissões, políticas e utilização, consulte Governação de um MCP.

Liga as competências manualmente

Para expor as competências publicadas do Unity Gateway como ferramentas, regista o registo de competências 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>"

Substitui os marcadores de lugar pelo teu espaço de trabalho, token e esquema de habilidades. Mantenha a barra à direita 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 ligação com /mcp. Peça ao Claude para usar uma competência pelo nome completo, como: Use <catalog>.<schema>.<skill-name> to review this query. Esta ligação expõe competências como ferramentas MCP; ug skills add transfere competências para deteção nativa em alternativa.

Aplicação de ambiente de trabalho Claude

1. Obter um ID de cliente OAuth

Pede ao administrador da tua conta para criar uma ligação de aplicação OAuth. Na consola de contas Azure Databricks, abrir Definições > Ligações > da aplicação Adicionar ligação e utilizar:

Configurações	Valor
Tipo de identidade	Aplicação padrão
Nome do aplicativo	`claude-desktop`
Gerar um segredo do cliente	Desverificado (cliente público)
URL de redirecionamento	`http://127.0.0.1:53180/callback`
Âmbitos de acesso	`ai-gateway`

Guarda a ligação e copia o ID do Cliente. Se tenciona associar competências, registe-se também em http://127.0.0.1:53280/callback.

2. Liga-te ao Unity Gateway

No ecrã de início de sessão da aplicação para computador, selecione Ajuda > Resolução de Problemas > Ativar o Modo de Programador e, em seguida, Programador > Configurar inferência de terceiros.

Na página de Ligação , selecione Gateway e introduza:

Configurações	Valor
Tipo de credencial	Início de sessão interativo
URL de base do gateway	`https://<workspace-hostname>/ai-gateway/anthropic`
ID de Cliente	O seu ID de cliente OAuth
URL do emissor	`https://<workspace-hostname>/oidc`
Token de autenticação ao portador	Token de acesso
Scopes	`ai-gateway`
Anexar `offline_access`	Enabled
Porta de redirecionamento	`53180`

Substitua <workspace-hostname> pelo nome de host do seu workspace Azure Databricks. Deixe as outras definições nos valores predefinidos. Consulte a configuração do gateway da Anthropic para obter detalhes sobre os campos.

Clique em Testar ligação e inicie sessão no Azure Databricks. Selecione Aplicar Alterações, depois Guardar e Reiniciar. No ecrã de iniciação de sessão, escolha a configuração de terceiros e inicie uma conversa no Code ou no Cowork.

3. Adicionar ferramentas e competências MCP

Desenvolvedores > Abertos Configuram Conectores de Inferência > de Terceiros. Na secção Servidores MCP Geridos, adicione uma entrada para cada MCP ou registo de competências que queira usar.

Use estas definições para ambos os tipos de conectores:

Configurações	Valor
Transportes	HTTP para Transmissão Contínua
OAuth	Traga o seu próprio cliente
ID de Cliente	O seu ID de cliente OAuth
Segredo do cliente	Deixar em branco
Servidor de autorização	`["https://<workspace-hostname>/oidc"]`
Scope	`ai-gateway`
Pedido `offline_access`	Enabled
Anfitrião de retorno de chamada	`127.0.0.1`

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

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

Para as competências, dê um nome ao conector databricks-skill-registry, defina Porta de callback para 53280 e utilize:

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

Mantenha a barra à direita antes de ?schema. Para incluir múltiplos esquemas, repita o parâmetro: ?schema=main.default&schema=ml.prod. Estas capacidades são disponibilizadas ao Claude como ferramentas por meio do conector.

Para cada conector, clique em Iniciar sessão e testar e complete o login. Selecione Aplicar Alterações, depois Guardar e Reiniciar. Peça ao Claude para usar uma ferramenta conectada ou uma habilidade pelo respetivo nome completo. Consulte Adicionar ferramentas e competências para requisitos de acesso e mais opções.

Conectores Claude

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

Use um conector personalizado para adicionar ferramentas Azure Databricks MCP ao Claude na Web ou no ambiente de trabalho, utilizando a sua conta Claude.

Peça a um administrador de conta para criar um cliente OAuth. Para um MCP, selecione o ai-gateway âmbito e registe ambos os URLs de redirecionamento:
- https://claude.ai/api/mcp/auth_callback
- https://claude.com/api/mcp/auth_callback
No Claude, abre Definições > Conectores > Adicionar conector personalizado.

Introduza o URL do MCP:

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

Introduza o ID do cliente OAuth e, para um cliente confidencial, o seu segredo. Clique em Adicionar e conclua o início de sessão.
Numa conversa, ativa o conector e pede ao Claude para chamar uma das suas ferramentas. Para system.ai.dbsql, tente SELECT 1 AS result.

Se o seu espaço de trabalho restringir IPs de entrada, permita os IPs de saída do Claude. Consulte autenticação MCP e rede para permissões, login do fornecedor e resolução de problemas.

Utilize um token de acesso pessoal no Claude desktop para testes locais

Esta opção requer Node.js com npx e um token de acesso pessoal. Funciona para MCPs fornecidos e registados pelo Databricks, bem como para endpoints de workspace legados. Os servidores alojados em Databricks Apps requerem OAuth.

Intercale esta entrada em claude_desktop_config.json em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no Windows:

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

Substitui os marcadores de lugar, mantém os tokens fora do controlo de versão e reinicia o desktop do Claude. Pede ao Claude para invocar uma ferramenta só de leitura para verificar a ligação.

Troubleshooting

Claude Code não se liga: Execute ug doctor se usar ug. Para a configuração manual, verifica o nome do anfitrião do espaço de trabalho, o token, o nome do modelo e as permissões do modelo.
Falha no início de sessão no ambiente de trabalho: Verifique o ID do cliente, /oidc o emissor e ai-gateway o âmbito. O URL de redirecionamento registado deve corresponder ao host e à porta do conector: 53180 para modelos e MCPs, ou 53280 para competências neste guia. As alterações na aplicação do OAuth podem demorar até 30 minutos a entrar em vigor.
Falta um modelo de ambiente de trabalho: Verifique as permissões do seu 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, por isso inclui todos os modelos que queres usar. Aplica as alterações e reinicia.
Um MCP ou conector de skill falha: Verifique o seu URL e permissões. O campo do servidor de autorização deve conter o array JSON mostrado acima. Clique em Iniciar sessão e teste para inspecionar o erro.
O login no espaço de trabalho funciona, mas uma ferramenta pede-lhe para iniciar sessão: Abra o link de login devolvido pelo MCP, inicie sessão no fornecedor externo e depois tente novamente a chamada. O espaço de trabalho e o início de sessão do fornecedor são etapas separadas.
Claude Code OAuth reporta um desajuste de redirecionamento ou a ligação expira: Para uma aplicação OAuth personalizada, faça corresponder o URL de redirecionamento ao host e à porta de callback, e verifique o acesso à rede. As alterações da aplicação OAuth podem demorar até 30 minutos a entrar em vigor.

Passos seguintes

Comentários

Esta página foi útil?

Última atualização a 2026-10-08