Solución de problemas de SQL MCP Server

Soluciones para problemas comunes de configuración de transporte, permiso y integración de cliente de IA de SQL MCP Server en el generador de API de datos.

Preguntas frecuentes

¿Qué es SQL MCP Server en DAB?

Data API Builder incluye un servidor integrado de Protocolo de contexto de modelo (MCP) que expone entidades de base de datos configuradas como herramientas que pueden invocar los agentes de INTELIGENCIA artificial y los clientes del modelo de lenguaje. El servidor MCP permite a los clientes de inteligencia artificial consultar y manipular datos a través del mismo modelo de entidades y permisos que usan los puntos de conexión REST y GraphQL.

¿Qué protocolos de transporte usa el servidor MCP?

DAB admite dos modos de transporte MCP: stdio para clientes basados en procesos locales y http (Eventos Server-Sent) para clientes remotos o en red. El transporte se configura en dab-config.json bajo runtime.mcp. La mayoría de los clientes de inteligencia artificial local usan el transporte stdio, como extensiones de VS Code y agentes de escritorio. El transporte HTTP se usa para clientes hospedados en la nube, como Azure AI Foundry.

¿Qué clientes de IA son compatibles?

Cualquier cliente compatible con MCP puede conectarse al servidor MCP de DAB. Los clientes probados incluyen GitHub Copilot en Visual Studio Code, agentes de Azure AI Foundry y otras herramientas que implementan la especificación del protocolo de contexto de modelo. Consulte la documentación del cliente para obtener instrucciones sobre cómo registrar un punto de conexión de servidor MCP.

Problemas comunes

El servidor MCP no aparece en el cliente

Síntoma: El cliente de IA no muestra herramientas DAB o el servidor MCP no aparece en la lista de servidores del cliente.

Causa: El cliente está configurado para el transporte stdio, pero DAB no está registrado como un servidor MCP en el archivo de configuración del cliente o el proceso DAB no se está ejecutando.

Resolución: Agregue DAB a la configuración del servidor MCP del cliente. Para GitHub Copilot de VS Code, agregue una entrada a .vscode/mcp.json con el command establecido en dab y con el args establecido en ["start", "--no-https-redirect"]. Confirme que DAB se está ejecutando y que el campo runtime.mcp.enabled está establecido en true en dab-config.json.

Fallo en la llamada a la herramienta debido a un error de permisos

Síntoma: El cliente de IA recibe un error de permiso denegado o no autorizado al invocar una herramienta DAB.

Causa: El rol anónimo o del sistema no tiene configurada la acción necesaria para la entidad en dab-config.json.

Resolución: Compruebe la permissions matriz de la entidad. Asegúrese de que el rol usado por el cliente MCP (normalmente anonymous para el uso local no autenticado) tiene las readacciones necesarias , create, updateo delete . Use dab update --permissions para agregar las acciones necesarias y, a continuación, reinicie DAB.

Descripciones de entidad no visibles para el agente

Síntoma: El agente de IA no puede determinar qué herramientas están disponibles o genera llamadas a herramientas incorrectas porque carece de contexto sobre las entidades.

Causa: Las descripciones de entidad y campo no se establecen en dab-config.json, por lo que el servidor MCP expone herramientas sin metadatos descriptivos para que el modelo de lenguaje lo use.

Resolución: Agregue descripciones a cada entidad y sus campos en dab-config.json mediante la description propiedad . Las descripciones claras mejoran la capacidad del modelo de lenguaje para seleccionar la herramienta correcta y construir consultas válidas. Use dab update --description para establecer descripciones de nivel de entidad desde la línea de comandos.

Error de autenticación al conectarse desde Azure AI Foundry

Síntoma: Un agente de Azure AI Foundry no se puede autenticar con el servidor MCP DAB con un error de validación de token o 401 Unauthorized.

Causa: El host DAB solo está configurado para el acceso anónimo o la identidad administrada del agente Foundry no se le ha concedido acceso al host DAB o a la base de datos subyacente.

Resolución: Configure DAB para aceptar tokens de Microsoft Entra, configurando host.authentication.provider a StaticWebApps o AzureAD y proporcionando la audiencia correcta. Asegúrese de que a la identidad administrada del agente de Foundry se le asigna el rol adecuado en el modelo de permisos DAB y de que la identidad tiene acceso a la base de datos. Para servidores back-end de Azure SQL, cree un usuario de base de datos para la identidad administrada con CREATE USER [agent-identity] FROM EXTERNAL PROVIDER.

Las agregaciones no están disponibles para las entidades de Cosmos DB a través de herramientas de MCP

Síntoma: Un agente de IA que intenta agregar datos (recuento, suma, promedio) de una entidad respaldada por Cosmos DB no recibe ningún resultado o error.

Causa: Data API Builder no admite operaciones de agregación para Azure Cosmos DB. Las llamadas de herramienta MCP que se traducen en consultas agregadas producirán un error en las entidades de Cosmos DB. Se trata de una limitación conocida que se monitoriza en la incidencia de GitHub n.º 2849.

Resolución: Dirija al agente para recuperar el conjunto de resultados completo y realizar agregaciones en la aplicación o lógica del agente que realiza la llamada. Siga la incidencia de GitHub para obtener actualizaciones sobre cuándo se añadirá la compatibilidad con agregaciones de Cosmos DB.