Conectar Claude Code

Utiliza Claude Code o la aplicación de escritorio Claude con modelos, herramientas MCP y habilidades a través de Unity Gateway. Para Claude Code, utiliza la CLI de Unity Gateway (ug) o configura la conexión manualmente. Para la app de escritorio, configura la conexión en la configuración de la app.

Para conectar herramientas a una configuración existente de Claude Code, ve a Añadir herramientas MCP. Para Claude en la web o en una sesión de escritorio usando tu cuenta Claude, usa Claude connectors.

Prerequisites

Necesitas la URL de tu espacio de trabajo de Azure Databricks y el acceso a los modelos que quieres usar. Para la configuración de escritorio, instala la última aplicación de escritorio de Claude y pide a tu administrador de cuenta un ID de cliente OAuth, como se describe a continuación.

Si tu administrador ya ha configurado tu dispositivo, sigue las instrucciones de inicio de sesión y lanzamiento de tu organización.

Claude Code

Usa la CLI de Unity Gateway (recomendada)

Instala ug, y luego ejecuta este comando desde el directorio de tu proyecto:

ug claude

Sigue las indicaciones para seleccionar tu espacio de trabajo e iniciar sesión. ug configura la conexión y abre Claude Code en tu terminal. Empieza a usar las mismas indicaciones y comandos que ya usas. Para cambiar de modelo, introduce /model.

Sigue añadiendo herramientas MCP para conectar datos y servicios. Para descargar habilidades compartidas, corre ug skills add y selecciona las habilidades que quieras. Consulta Añadir herramientas y habilidades para más opciones.

Configurar el código Claude manualmente

Fusiona los siguientes ajustes en ~/.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"
  }
}

Sustituye <workspace-hostname> por el nombre de host de tu espacio de trabajo, sin https://. Establezca <model-api-name> en el nombre completo de Unity Catalog de la API de modelos Claude a la que tenga acceso y proporcione el token de acceso personal de Azure Databricks.

Ejecuta claude desde el directorio de tu proyecto. Para otros ajustes, consulta la configuración de Claude Code.

Añadir herramientas MCP

Para usar system.ai.dbsql, system.ai.sandbox o system.ai.web_search, un administrador de cuenta debe habilitar la beta de Unity Gateway desde la página de Previews de la consola de la cuenta. Consulte Administrar vistas previas de la cuenta.

Abre los MCPs de Unity Gateway > en tu espacio de trabajo. Elige un MCP integrado o registra tu servidor MCP externo.
Copia el nombre completo del MCP, como system.ai.github o <catalog>.<schema>.<service>.
Confirma que tienes acceso al MCP.
Después de instalar ug, agregue el MCP a Claude Code:
```
ug mcp add --agents claude --names <catalog>.<schema>.<service>
```
Sustituye el marcador por el nombre que copiaste. Por ejemplo, usa --names system.ai.github para GitHub. Para elegir servicios de forma interactiva, omite --names.

En la primera configuración, sigue las indicaciones para seleccionar tu espacio de trabajo, iniciar sesión y elegir un modelo. ug configura tanto el acceso al modelo como al MCP y actualiza las credenciales. Reinicia Claude Code con ug claude, y luego prueba una herramienta.

Añadir herramientas MCP manualmente

Utiliza el cliente OAuth integrado que aparece a continuación, o configura tu propia app OAuth. Para añadir un MCP con el cliente integrado, ejecuta:

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

Sustituye el nombre de host/servidor y el nombre de MCP. Esto utiliza el cliente OAuth integrado claude-code . Abre Claude Code, introduce /mcp, e inicia sesión en el servidor con tu cuenta de Azure Databricks. Repite con un nombre de servidor diferente para cada MCP que quieras añadir y luego prueba una herramienta.

Usa tu propia app OAuth

Haz que un administrador de cuenta abra Configuración > Conexiones de aplicaciones > Añadir conexión en la consola de cuentas.
Introduce un nombre como claude-code-mcp, desmarca Generar un secreto de cliente para un cliente público, establece la URL de redirección en http://localhost:8080/callback y selecciona el alcance ai-gateway. Guarda y copia el ID del cliente. Consulta cómo crear una aplicación OAuth.

Registra el MCP usando ese ID de cliente y el puerto de callback correspondiente:

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

Abre Claude Code, introduce /mcp, e inicia sesión. Si tu organización necesita un cliente confidencial, añade --client-secret al comando e introduce el secreto cuando te lo pidan.

Prueba una herramienta MCP

En Claude Code, introduce /mcp y comprueba que el servidor está conectado.
Pide a Claude que liste las herramientas de ese servidor y luego solicita una operación de lectura. Para GitHub, pídele que encuentre un issue en un repositorio al que puedas acceder. Para un servidor personalizado, usa una herramienta y entradas que probaste durante el registro.
Si una llamada de herramienta te pide iniciar sesión, abre el enlace de inicio de sesión que te devuelve el MCP, completa el consentimiento del proveedor y luego vuelve a intentar la llamada.
Comprueba que Claude haga una llamada a la herramienta y devuelva su resultado. Una respuesta por texto por sí sola no verifica la conexión.

Para usar datos de Azure Databricks, conecta system.ai.genie_one_mcp para preguntas de negocio o system.ai.dbsql para SQL. Por ejemplo, pide al MCP SQL que ejecute SELECT 1 AS result.

Para permisos, políticas y uso, véase Administrar un MCP.

Conecta habilidades manualmente

Para exponer las habilidades publicadas de Unity Gateway como herramientas, registra el registro de habilidades como un 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>"

Sustituye los marcadores de posición por tu espacio de trabajo, token y esquema de habilidades. Mantén la barra final antes de ?schema. Para incluir varios esquemas, repita el parámetro: ?schema=main.default&schema=ml.prod.

Reinicia Claude Code y comprueba la conexión con /mcp. Pide a Claude que use una habilidad por su nombre completo, como Use <catalog>.<schema>.<skill-name> to review this query.. Esta conexión expone las habilidades como herramientas MCP; ug skills add descarga habilidades para su detección nativa en su lugar.

Aplicación de escritorio Claude

1. Consigue un ID de cliente OAuth

Pide a tu administrador de cuenta que cree una conexión de aplicación OAuth. En la consola de cuentas de Azure Databricks, abra Configuración > Conexiones de aplicaciones > Añadir conexión y use:

Setting	Value
Tipo de identidad	Aplicación estándar
Nombre de la aplicación	`claude-desktop`
Generar un secreto de cliente	No seleccionado (cliente público)
URL de redirección	`http://127.0.0.1:53180/callback`
Ámbitos de acceso	`ai-gateway`

Guarda la conexión y copia el ID del cliente. Si planeas conectar habilidades, también regístrate http://127.0.0.1:53280/callback.

2. Conectarse a Unity Gateway

Desde la pantalla de inicio de sesión de la aplicación de escritorio, selecciona Ayuda > Solución de problemas > Activar modo de desarrollador, luego Desarrollador > Configurar inferencia de terceros.

En la página de Conexión , selecciona Gateway e introduzca:

Setting	Value
Tipo de credenciales	Inicio de sesión interactivo
URL base de la puerta de enlace	`https://<workspace-hostname>/ai-gateway/anthropic`
Id de cliente	Tu ID de cliente OAuth
Dirección URL del emisor	`https://<workspace-hostname>/oidc`
Token de portador	Token de acceso
Ámbitos	`ai-gateway`
Añadir `offline_access`	habilitado
Puerto de redireccionamiento	`53180`

Sustituye <workspace-hostname> por el nombre de host de tu espacio de trabajo de Azure Databricks. Deja los demás ajustes en sus valores predeterminados. Consulta la configuración de la puerta de entrada de Anthropic para detalles de campo.

Haz clic en Probar conexión e inicia sesión en Azure Databricks. Selecciona Aplicar cambios y luego guarda y reinicia. En la pantalla de inicio de sesión, elige la configuración de terceros y inicia una conversación en Code o Cowork.

3. Añadir herramientas y habilidades MCP

Abra Desarrollador > Configurar inferencia de terceros > Conectores. En la sección Servidores MCP gestionados, añade una entrada para cada MCP o registro de habilidades que quieras usar.

Utiliza estos ajustes para ambos tipos de conectores:

Setting	Value
Transport	HTTP en transmisión
OAuth	Lleva a tu propio cliente
Id de cliente	Tu ID de cliente OAuth
Secreto de cliente	Dejar en blanco.
Servidor de autorización	`["https://<workspace-hostname>/oidc"]`
Ámbito	`ai-gateway`
Solicitud `offline_access`	habilitado
Host de devolución de llamada	`127.0.0.1`

Para un MCP, busca su nombre de tres partes bajo Unity Gateway > MCPs en tu espacio de trabajo. Ponle al conector un nombre descriptivo, configura el puerto de Callback en 53180, y usa esta URL:

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

Para habilidades, nombra el conector databricks-skill-registry, configura el puerto de Callback en 53280, y usa:

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

Mantén la barra final antes de ?schema. Para incluir varios esquemas, repita el parámetro: ?schema=main.default&schema=ml.prod. Estas habilidades se presentan a Claude como herramientas a través del conector.

Para cada conector, haz clic en Iniciar sesión y probar y completa el inicio de sesión. Selecciona Aplicar cambios y luego guarda y reinicia. Pide a Claude que use una herramienta conectada o una habilidad con su nombre completo. Consulta Añadir herramientas y habilidades para requisitos de acceso y más opciones.

Claude connectors

Para system.ai.dbsql, primero activa la beta de Unity Gateway.

Usa un conector personalizado para añadir herramientas MCP de Azure Databricks a Claude en la web o escritorio usando tu cuenta de Claude.

Haz que un administrador de cuentas cree un cliente OAuth. Para un MCP, selecciona el ai-gateway ámbito y registra ambas URLs de redirección:
- https://claude.ai/api/mcp/auth_callback
- https://claude.com/api/mcp/auth_callback
En Claude, abre Configuraciones > Conectores > Añade conector personalizado.

Introduce la URL del MCP:

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

Introduce el ID de cliente OAuth y, para un cliente confidencial, su secreto. Haz clic en Añadir y completa el proceso de inicio de sesión.
En una conversación, activa el conector y pide a Claude que llame a una de sus herramientas. Para system.ai.dbsql, prueba SELECT 1 AS result.

Si tu espacio de trabajo restringe las IPs entrantes, permite las IPs salientes de Claude. Consulta autenticación y red MCP para permisos, inicio de sesión del proveedor y resolución de problemas.

Utiliza un token de acceso personal en Claude Desktop para pruebas locales

Esta opción requiere Node.js con npx y un token de acceso personal. Funciona para MCPs proporcionados y registrados por Databricks, así como para endpoints de espacios de trabajo heredados. Los servidores alojados en Databricks Apps requieren OAuth.

Combine esta entrada en claude_desktop_config.json en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en 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>"
      ]
    }
  }
}

Sustituye los marcadores, mantén los tokens fuera del control de versiones y reinicia el escritorio de Claude. Pide a Claude que llame a una herramienta de solo lectura para verificar la conexión.

Troubleshooting

Claude Code no se conecta: Ejecuta ug doctor si usas ug. Para la configuración manual, comprueba el nombre de host del espacio de trabajo, el token, el nombre del modelo y los permisos del modelo.
Error al iniciar sesión en el escritorio: Comprueba el ID del cliente, /oidc el emisor y ai-gateway el alcance. La URL registrada de redirección debe coincidir con el host y puerto del conector: 53180 para modelos y MCPs, o 53280 para las habilidades de esta guía. Los cambios en la aplicación de OAuth pueden tardar hasta 30 minutos en hacer efecto.
Falta un modelo de escritorio: Comprueba los permisos de tu modelo. En Modelos de conexión > Lista de modelos >, añada el nombre completo del modelo en Unity Catalog. Una lista explícita sustituye al descubrimiento automático, así que incluye todos los modelos que quieras usar. Aplica los cambios y reinicia.
Un MCP o un conector de habilidades falla: Comprueba su URL y permisos. El campo del servidor de autorización debe contener el array JSON mostrado arriba. Haz clic en Iniciar sesión y probar para inspeccionar el error.
El inicio de sesión en el espacio de trabajo funciona, pero una herramienta te pide iniciar sesión: Abre el enlace de inicio de sesión que devuelve el MCP, inicia sesión con el proveedor externo y luego vuelve a intentar la llamada. El espacio de trabajo y el inicio de sesión con el proveedor son pasos separados.
Claude Code OAuth informa de un desajuste de redirección o se agota el tiempo de espera de la conexión: Para una aplicación OAuth personalizada, haz coincidir su URL de redirección con el host y puerto de callback, y comprueba el acceso a la red. Los cambios en la app de OAuth pueden tardar hasta 30 minutos en hacer efecto.

Pasos siguientes

Comentarios

¿Le resultó útil esta página?

Última actualización el 2026-10-08