Conectar o Claude Code

Use o Claude Code com modelos, ferramentas MCP e skills por meio do Unity Gateway. Use a CLI do Unity Gateway (ug) para configurar o acesso ou configure a conexão manualmente.

Para conectar ferramentas a uma configuração existente do Claude Code, vá para Adicionar ferramentas MCP.

Pré-requisitos

Você precisa da URL do seu workspace Databricks, acesso aos modelos que você deseja usar e o Claude Code mais recente.

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.

Use a CLI do Unity Gateway (recomendado)

Instale o ug e execute este comando a partir do diretório do seu projeto:

Bash
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.

Continue para Add MCP tools para conectar dados e serviços. Para fazer download de skills compartilhadas, execute ug skills add e selecione as skills desejadas. Consulte Add tools and skills para obter mais opções.

Configure o Claude Code manualmente

Faça o merge das seguintes configurações em ~/.claude/settings.json:

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.

Modo automático

O modo automático reduz prompts de permissão de rotina ao verificar chamadas de ferramenta propostas com um classificador de segurança.

Modelos da Anthropic por meio do Unity Gateway usam as verificações de modo automático nativas da Anthropic. Para modelos de base não pertencentes à Anthropic hospedados pelo Databricks que oferecem suporte a chamadas de função, o Unity Gateway fornece o classificador. Para a lista de modelos mantidos e as capacidades por modelo, consulte Modelos disponíveis através do Databricks.

O Claude Code avalia regras explícitas permissions.deny e regras de escopo de conteúdo permissions.ask antes de consultar o classificador. Uma regra de negação correspondente bloqueia a ação, e uma regra de solicitação correspondente exige um prompt de permissão. O modo automático também pode bloquear ações com base na conversa e nas regras do classificador, ou quando uma verificação não consegue gerar um veredito válido.

Depois de configurar sua conexão com ug, começar o Claude Code no modo automático:

Bash
ug claude -- --permission-mode auto

Com uma conexão manual, execução claude --permission-mode auto. Para encaminhamento de argumento ug, consulte referência de CLI ug.

Configurar infraestrutura confiável

Descreva os repository, domains e serviços confiáveis da sua organização em autoMode.environment. Essas entradas ajudam o classificador a distinguir o acesso esperado à sua infraestrutura de ações que ele deve bloquear. Faça merge de um bloco autoMode nas suas configurações de usuário em ~/.claude/settings.json, por exemplo:

JSON
{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/example-org and its repositories",
      "Trusted internal services: builds.internal.example.com"
    ]
  }
}

Substitua as entradas de exemplo pela infraestrutura da sua organização. As entradas são descrições em linguagem natural. Mantenha "$defaults" para preservar as entradas de ambiente integradas ao adicionar as suas próprias.

O classificador lê autoMode das configurações do usuário, configurações gerenciadas ou configuração --settings em linha. Ele não lê este bloco do projeto .claude/settings.json ou .claude/settings.local.json. Os administradores podem distribuir configurações compartilhadas por meio de configurações gerenciadas.

Para personalização de regras, configurações gerenciadas e revisão de ações bloqueadas, veja Configurar o modo automático.

Acompanhar o uso do classificador

As verificações do Unity Gateway enviam os argumentos de ferramenta propostos e o contexto da conversa para um modelo de classificador separado. As solicitações do classificador incorrem em custos adicionais de modelo e podem aumentar a latência.

As solicitações de classificador aparecem em system.ai_gateway.usage com invocation_metadata.source definido para SAFEGUARD_CLASSIFIER. Use este valor para distinguir solicitações de verificação de segurança e seu uso de tokens e latência das solicitações do seu modelo de codificação. Veja Acompanhamento de uso para requisitos de acesso e o esquema da tabela de uso.

Adicionar ferramentas MCP

Para usar system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, um administrador de account deve habilitar a versão beta do Unity Gateway na página Previews do console da account. Consulte Gerenciar prévias da account.

Abra Unity Gateway > MCPs em seu workspace. Escolha um MCP integrada ou registro seu servidor MCP externo.
Copie o nome completo do MCP, como system.ai.github ou <catalog>.<schema>.<service>.
Confirme que você tem acesso ao MCP.
Após instalar ug, adicione o MCP ao Claude Code:
Bash
```
ug mcp add --agents claude --names <catalog>.<schema>.<service>
```
Substitua o espaço reservado 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 workspace, fazer login e escolher um modelo. ug configura o acesso ao modelo e ao MCP e faz refresh das credenciais. Reinicie o Claude Code com ug claude e, em seguida, teste uma ferramenta.

Adicionar ferramentas MCP manualmente

Use o ID de cliente default do Claude Code abaixo ou configure seu próprio aplicativo OAuth. Para adicionar um MCP com o ID de cliente default, execução:

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

Substitua o hostname, workspace ID e o nome do MCP. Abra o Claude Code, digite /mcp e faça login no servidor com sua account Databricks. Repita com um nome de servidor diferente para cada MCP que você deseja adicionar e, em seguida, teste uma ferramenta.

Use seu próprio aplicativo OAuth

Peça a um administrador de account que abra Settings > App connections > Add connection no console da account.
Insira um nome como claude-code-mcp, desmarque Generate a client secret para um cliente público, defina a URL de redirecionamento como http://localhost:8080/callback e selecione o escopo ai-gateway. Salve e copie o Client ID . Consulte Criar um aplicativo OAuth.

Registro o MCP usando esse ID do cliente e a porta de retorno de chamada correspondente:

Bash
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>?o=<workspace-id>"

Abra o Claude Code, insira /mcp e faça login. Se a sua organização exigir um cliente confidencial, adicione --client-secret ao comando e insira o segredo quando solicitado.

Testar uma ferramenta MCP

No Claude Code, insira /mcp e verifique se o servidor está conectado.
Peça ao Claude para listar as ferramentas desse servidor e, em seguida, solicite uma operação de leitura. Para o GitHub, peça para ele encontrar um problema em um repository que você possa acessar. Para um servidor personalizado, use uma ferramenta e as entradas que você testou durante o registro.
Se uma chamada de ferramenta solicitar que você faça login, abra o link de login retornado pelo MCP, conclua o consentimento do provedor e tente a chamada novamente.
Verifique se o Claude faz uma chamada de ferramenta e retorna o resultado. Apenas uma resposta em texto não verifica a conexão.

Para usar os dados do Databricks, conecte system.ai.genie_one_mcp para perguntas de negócios ou system.ai.dbsql para SQL. Por exemplo, peça para o SQL MCP realizar a execução de SELECT 1 AS result.

Para obter informações sobre permissões, políticas e uso, consulte Govern an MCP.

Connect skills manually

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

Bash
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.

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.
O Claude Code OAuth relata uma incompatibilidade de redirecionamento ou a conexão esgota o tempo limite: Para um aplicativo OAuth personalizado, faça corresponder sua URL de redirecionamento ao host e à porta de retorno de chamada e verifique o acesso à rede. As alterações no aplicativo OAuth podem levar até 30 minutos para entrar em vigor.

Pré-requisitos​

Use a CLI do Unity Gateway (recomendado)​

Configure o Claude Code manualmente​

Modo automático​

Configurar infraestrutura confiável​

Acompanhar o uso do classificador​

Adicionar ferramentas MCP​

Adicionar ferramentas MCP manualmente​

Testar uma ferramenta MCP​

Connect skills manually​

Solução de problemas​

Passos seguintes​