Conexión de clientes que no son de Databricks a servidores MCP de Databricks

Conecte clientes que no son de Databricks (externos), asistentes de IA e IDE que admiten el Protocolo de contexto de modelo (MCP) a los servidores MCP de Databricks. Esto proporciona acceso a los datos y herramientas de Databricks directamente en el entorno de desarrollo.

Al conectar clientes externos a servidores MCP de Databricks, puede hacer lo siguiente:

• Acceso a las funciones, tablas y índices vectoriales del catálogo de Unity desde el IDE o el Asistente para IA
• Consulta de datos de Databricks directamente desde Claude, Cursor, Replit u otras herramientas habilitadas para MCP

Prerequisites

• Direcciones URL del servidor: obtenga las direcciones URL de servidor adecuadas para el servidor MCP de Databricks que desea usar:
  • Servidores MCP administrados
  • Servidores MCP externos
  • Servidores MCP personalizados
• Acceso a recursos: compruebe que la cuenta tiene acceso a los recursos del catálogo de Unity que desea usar.
• Acceso a la red: Si el área de trabajo tiene restricciones de IP, añade a la lista de permitidos las direcciones IP del cliente.

Métodos de autenticación

Elija el método de autenticación que mejor se adapte a sus requisitos de seguridad:

Conexión de clientes mediante la autenticación de OAuth

OAuth proporciona autenticación segura con permisos delimitados y actualización automática de tokens.

Obtén la URL de redireccionamiento de OAuth del cliente

Cada cliente MCP requiere direcciones URL de redirección de OAuth específicas para devoluciones de llamada de autenticación. Entre los patrones comunes de dirección URL de redireccionamiento se incluyen los siguientes:

• Clientes basados en web: https://<domain>/oauth/callback o https://<domain>/api/mcp/auth_callback
• Herramientas de desarrollo local: http://localhost:<port>/oauth/callback

Compruebe la documentación del cliente para encontrar las direcciones URL de redirección exactas necesarias.

Creación de la aplicación OAuth de Databricks

Haga que un administrador de cuenta cree una aplicación de OAuth de Databricks. Recupere su identificador de cliente y, si el cliente lo requiere, el secreto de cliente.

Basado en la interfaz de usuario (consola de cuenta)

Cree una aplicación de OAuth de Databricks mediante la consola de la cuenta:

1. En la consola de la cuenta de Databricks, vaya a Configuración> Conexiones de>Agregar conexión.

2. Configure las opciones de la aplicación:

   • Nombre: escriba un nombre descriptivo para la aplicación de OAuth (por ejemplo, claude-mcp-client, mcp-inspector).
   • Direcciones URL de redireccionamiento: agregue las direcciones URL de redireccionamiento requeridas por el cliente externo.
   • Tipo de cliente: para clientes públicos (basados en explorador, móviles), desactive Generar un secreto de cliente. En el caso de los clientes confidenciales (servidor), manténgalo comprobado.
   • Ámbitos: Configuración de los ámbitos de API (consulte Configuración de ámbitos de OAuth a continuación)
   • Caducidad del token: establecer tiempos adecuados de acceso y actualización del token

Interfaz de línea de comandos (CLI)

Cree una aplicación de OAuth de Databricks mediante la CLI de Databricks:

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

Reemplace por <your-client-redirect-url> la dirección URL de redireccionamiento real del cliente.

Configuración de ámbitos de OAuth

Los ámbitos de OAuth controlan a qué API de Databricks puede acceder el cliente. Para la mayoría de los casos de uso, use el all-apis ámbito , que concede acceso a todas las API de Databricks y es la opción más sencilla.

Para un control más granular, puede especificar ámbitos específicos de MCP en lugar de all-apis:

Para obtener más información sobre cómo declarar ámbitos de API REST y usarlos con agentes, consulte Declaración de ámbitos de API REST al registrar el agente.

Configuración del acceso a la red (opcional)

Si el área de trabajo de Databricks tiene restricciones de acceso IP, agregue las direcciones IP salientes de su cliente a la lista de autorización del área de trabajo. De lo contrario, el área de trabajo bloquea las solicitudes de autenticación del cliente. Consulte Administrar listas de acceso IP.

Configuración del cliente

Después de crear la aplicación OAuth en Databricks, configure el cliente MCP específico con las credenciales de OAuth. Cada cliente tiene su propio método de configuración. Consulte los siguientes ejemplos específicos de la plataforma para obtener instrucciones detalladas para clientes de MCP populares.

Ejemplos de OAuth

En los ejemplos siguientes se muestra cómo configurar clientes MCP específicos con autenticación de OAuth. Siga primero los pasos genéricos de configuración de OAuth de la sección anterior y, a continuación, use estos ejemplos para configurar el cliente específico.

MCP Inspector

El Inspector de MCP es una herramienta de desarrollo para probar y depurar servidores MCP.

Siga la configuración de autenticación de OAuth anterior con esta configuración específica del inspector:

• Redirección de URLs:
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug
• Tipo de cliente: Público (desactive Generar un secreto de cliente)

Configurar Inspector de MCP:

1. Ejecute el inspector: npx @modelcontextprotocol/inspector.
2. Establezca Tipo de transporte en Streamable HTTP.
3. Escriba la dirección URL del servidor MCP de Databricks.
4. En la sección Autenticación , agregue el identificador de cliente de OAuth.
5. Haga clic en Abrir configuración de autenticación y elija Flujo guiado o rápido .
6. Después de la autenticación correcta, pegue el token de acceso en Token de portador en la sección Autenticación de token de API .
7. Haga clic en Conectar.

Conectores de Claude

Conecte Claude a los servidores MCP administrados y externos de Databricks mediante Los conectores de Claude con MCP remoto.

Siga la configuración de autenticación de OAuth anterior con esta configuración específica de Claude:

• URL de redirección: https://claude.ai/api/mcp/auth_callback y https://claude.com/api/mcp/auth_callback
• Lista de direcciones IP permitidas (si es necesario): Agregar las direcciones IP salientes de Claude

Configurar Claude:

1. Vaya a Configuración >Conectores en Claude.
2. Haga clic en Agregar conector personalizado.
3. Escriba la dirección URL del servidor MCP de Databricks.
4. Escriba el identificador de cliente de la aplicación OAuth.
5. Haga clic en Agregar para finalizar.

Cursor/Windsurf

Para conectar de forma segura un IDE local como Cursor o Windsurf a un servidor MCP de Databricks, use mcp-remote con OAuth. Siga las instrucciones del repositorio mcp-remote para configurar mcp-remote. A continuación, siga la configuración de autenticación de OAuth para asegurarse de que OAuth esté configurado correctamente.

Configurar cursor o Windsurf:

1. Busque el archivo de configuración de MCP:

   • Cursor: ~/.cursor/mcp.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

2. En el archivo de configuración, agregue el servidor MCP:

   Para clientes de OAuth confidenciales (con secreto de cliente):

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
         ]
       }
     }
   }
   

   Para clientes públicos de OAuth (sin secreto de cliente):

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
         ]
       }
     }
   }
   

3. Reemplace por <your-workspace-hostname> el nombre de host del área de trabajo de Databricks.

4. Establezca la variable MCP_REMOTE_CLIENT_ID de entorno con el identificador de cliente de OAuth. Para clientes confidenciales, configure también MCP_REMOTE_CLIENT_SECRET con el secreto del cliente.

Conexión de clientes mediante la autenticación de token de acceso personal (PAT)

Los tokens de acceso personal proporcionan un método de autenticación más sencillo adecuado para el desarrollo, las pruebas y el acceso a corto plazo a los servidores MCP de Databricks.

1. Genere un token de acceso personal en el área de trabajo de Databricks. Consulte Autenticación con tokens de acceso personal (heredado) de Azure Databricks.

2. Configure el acceso a la red (opcional).

   Si el área de trabajo de Databricks tiene restricciones de acceso IP, agregue las direcciones IP salientes del cliente a la lista de permitidos. Consulte la documentación del cliente o la configuración de red del entorno de implementación para obtener las direcciones IP necesarias.

3. Configure el cliente.

   Después de generar el PAT, configure el cliente MCP para usarlo para la autenticación. Cada cliente tiene su propio método de configuración. Consulte los ejemplos específicos de la plataforma a continuación para obtener instrucciones detalladas para clientes de MCP populares.

Ejemplos de PAT

En los ejemplos siguientes se muestra cómo configurar clientes MCP específicos con autenticación de token de acceso personal. Siga primero la configuración de autenticación pat anterior y, a continuación, use estos ejemplos para configurar el cliente específico.

Cursor

Cursor admite MCP a través de su configuración.

1. Abra la configuración del cursor.

2. Agregue la siguiente configuración (adapte la dirección URL del servidor MCP elegido):

   {
     "mcpServers": {
       "uc-function-mcp": {
         "type": "streamable-http",
         "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
         "headers": {
           "Authorization": "Bearer <YOUR_TOKEN>"
         },
         "note": "Databricks UC function"
       }
     }
   }
   

3. Reemplace por <your-workspace-hostname> el nombre de host del área de trabajo de Databricks.

4. Reemplace <YOUR_TOKEN> con su token de acceso personal.

Claude Desktop

Claude Desktop puede conectarse a servidores MCP de Databricks mediante mcp-remote.

1. Busque el claude_desktop_config.json archivo:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Agregue la siguiente configuración (adapte la dirección URL del servidor MCP elegido):

   {
     "mcpServers": {
       "uc-function-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
           "--header",
           "Authorization: Bearer <YOUR_TOKEN>"
         ]
       }
     }
   }
   

3. Reemplace por <your-workspace-hostname> el nombre de host del área de trabajo de Databricks.

4. Reemplace <YOUR_TOKEN> con su token de acceso personal.

5. Reinicie Claude Desktop para que los cambios surtan efecto.

Replit

Replit admite la conexión a servidores MCP de Databricks a través de la configuración personalizada del servidor MCP.

1. En el área de trabajo de Replit, haga clic en Agregar servidor MCP.

2. Escriba la dirección URL del servidor MCP de Databricks, por ejemplo:

   https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
   

3. Agregue un encabezado personalizado:

   • Clave: Authorization
   • Valor: Bearer <YOUR_TOKEN>

Vea la documentación de MCP de Replit.

Limitaciones

• Registro de cliente dinámico: Databricks no admite flujos de OAuth de registro de cliente dinámicos para servidores MCP administrados, externos o personalizados. Los clientes externos y los IDEs que exigen el registro de cliente dinámico no se admiten mediante autenticación OAuth.
• Compatibilidad personalizada con tokens de acceso personal del servidor MCP: Los servidores MCP personalizados, que están hospedados en Databricks Apps, no admiten tokens de acceso personal para la autenticación.
• Autorización en nombre de: los servidores MCP personalizados hospedados en las aplicaciones de Databricks no admiten la autorización en nombre de un usuario.

Pasos siguientes

• Uso de servidores MCP administrados para conectar agentes a datos del catálogo de Unity
• Uso de servidores MCP externos para acceder a servicios de terceros
• Hospedar servidores MCP personalizados para herramientas específicas de la organización