Pular para o conteúdo principal
Última atualização em

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.

Para conectar ferramentas a uma configuração existente do Claude Code, vá para Adicionar ferramentas MCP. Para o Claude na Web ou em uma sessão de desktop usando sua account do Claude, use os conectores do Claude.

Pré-requisitos​

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:

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.

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.

  1. Abra Unity Gateway > MCPs em seu workspace. Escolha um MCP integrada ou registro 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 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 cliente OAuth integrado abaixo ou configure seu próprio aplicativo OAuth. Para adicionar um MCP com o cliente integrada, execução:

Bash
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 MCP. Isso usa o cliente OAuth claude-code integrado. Abra o Claude Code, insira /mcp e inicie sessão no servidor com sua account do Databricks. Repita com um nome de servidor diferente para cada MCP que deseja adicionar e, em seguida, teste uma ferramenta.

Use seu próprio aplicativo OAuth

  1. Peça a um administrador de account que abra Settings > App connections > Add connection no console da account.

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

  3. 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>"

  4. 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​

  1. No Claude Code, insira /mcp e verifique se o servidor está conectado.
  2. 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.
  3. 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.
  4. 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.

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

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

Contexto

Valor

Tipo de identidade

Aplicativo 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 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

https://<workspace-hostname>/ai-gateway/anthropic

ID do cliente

Seu ID de cliente OAuth

URL do emissor

https://<workspace-hostname>/oidc

Bearer token

access token

Escopos

ai-gateway

Acrescentar offline_access

Ativada

Porta de redirecionamento

53180

Contexto

Valor

Tipo de credencial

Entrada interativa

URL base do gateway

https://<workspace-hostname>/ai-gateway/anthropic

ID do cliente

Seu ID de cliente OAuth

URL do emissor

https://<workspace-hostname>/oidc

Bearer token

access token

Escopos

ai-gateway

Acrescentar offline_access

Ativada

Porta de redirecionamento

53180

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​

Open Developer > Configure Third-Party Inference > Connectors . Em Gerenciado MCP servers , adicione uma entrada para cada MCP ou registro de habilidade 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

["https://<workspace-hostname>/oidc"]

Escopo

ai-gateway

Solicitado offline_access

Ativada

Host de retorno de chamada

127.0.0.1

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

["https://<workspace-hostname>/oidc"]

Escopo

ai-gateway

Solicitado offline_access

Ativada

Host de retorno de chamada

127.0.0.1

Para um MCP , encontre seu nome de três partes em Unity Gateway > MCPs no seu Workspace. Atribua ao conector um nome descritivo, defina Porta de callback como 53180 e use esta URL:

Text
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:

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

Conectores do Claude​

Para system.ai.dbsql, primeiro habilite o Unity Gateway beta.

Use um conector personalizado para adicionar ferramentas MCP do Databricks ao Claude na Web ou no desktop usando sua account do Claude.

  1. Peça a um account admin que crie um cliente OAuth. Para um MCP, selecione o escopo ai-gateway e faça o registro de ambos os URLs de redirecionamento:

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

  2. In Claude, open Settings > Connectors > Add custom connector .

  3. Insira o URL do MCP:

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

  4. Insira o ID do cliente OAuth e, para um cliente confidencial, o seu segredo. Clique em Adicionar e conclua o início de sessão.

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

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

Use a personal access token in Claude desktop for local testing

Esta opção requer Node.js com npx e um access token pessoal. Funciona para MCPs fornecidos e registrados pelo Databricks e para endpoints de workspace legados. Os servidores hospedados no Databricks Apps requerem OAuth.

Faça o merge desta 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:

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

Substitua os placeholders, mantenha os tokens fora do controle de versão e reinicie o Claude desktop. Peça para o Claude chamar uma ferramenta somente leitura para verificar a conexão.

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.

  • Falha no logon na área de trabalho: verifique o ID do cliente, o emissor de /oidc e o escopo de ai-gateway. O URL de redirecionamento registrado deve corresponder ao host e à porta do conector: 53180 para modelos e MCPs, ou 53280 para habilidades neste guia. As alterações no aplicativo OAuth podem levar até 30 minutos para entrar 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.

  • O início de sessão do workspace funciona, mas uma ferramenta pede para você fazer log in: abra o link de login retornado pelo MCP, faça login no provedor externo e tente a chamada novamente. O acesso do Workspace e do provedor são os passos separados.

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

Passos seguintes​

Nesta página