Conexión de agentes de IA a Fabric API para GraphQL con un servidor de Protocolo de contexto de modelo local (MCP)

Imagine preguntar a GitHub Copilot "Mostrarme todas las ventas del último trimestre" y hacer que consulte automáticamente el almacenamiento de datos de Fabric, comprenda el esquema y devuelva resultados, todo ello sin escribir una sola línea de GraphQL. En este tutorial se muestra cómo hacerlo posible.

En este tutorial, creará un servidor MCP de GraphQL local que actúa como un puente entre los agentes de inteligencia artificial y los datos de Microsoft Fabric. Al final, tiene un servidor de desarrollo en funcionamiento que permite a los asistentes de inteligencia artificial como GitHub Copilot, Claude y otros agentes de inteligencia artificial consultar de forma natural los datos de Fabric mediante lenguaje conversacional.

Podrá:

Configuración de la autenticación para que el servidor MCP de GraphQL pueda acceder de forma segura a Fabric
Habilite la introspección de esquema para que los agentes de IA puedan detectar automáticamente la estructura de datos.
Implementación de un servidor MCP de GraphQL local que traduce lenguaje natural en consultas graphQL
Conecta GitHub Copilot u otras herramientas de inteligencia artificial para consultar tus datos de forma conversacional

¿Cuál es el protocolo de contexto de modelo (MCP)?

El Protocolo de contexto de modelo (MCP) es un estándar para conectar asistentes de IA a los sistemas donde residen los datos, incluidos repositorios de contenido, herramientas empresariales y entornos de desarrollo. Su objetivo es ayudar a los modelos de frontera a producir mejores respuestas más relevantes. Piense en MCP como un puerto de USB-C para aplicaciones de inteligencia artificial. Al igual que USB-C proporciona una manera estandarizada de conectar los dispositivos a diversos periféricos y accesorios, MCP proporciona una manera estandarizada de conectar modelos de INTELIGENCIA ARTIFICIAL a orígenes de datos y herramientas externos.

Las principales plataformas de inteligencia artificial, como OpenAI, Microsoft Copilot Studio y Microsoft Foundry adoptaron MCP como una manera estándar de integrar agentes de inteligencia artificial con sistemas externos. Esto hace que MCP sea una opción ideal para conectar agentes de INTELIGENCIA ARTIFICIAL a los datos de Microsoft Fabric.

Por qué GraphQL es ideal para MCP

GraphQL es adecuado para integraciones de MCP porque:

Introspección de esquema: los agentes de IA pueden detectar automáticamente las estructuras de datos y las relaciones disponibles directamente desde el esquema graphQL.
Consultas flexibles: los agentes pueden solicitar exactamente los datos que necesitan en una sola solicitud.
Seguridad de tipos: la escritura segura ayuda a los agentes de inteligencia artificial a comprender los formatos de datos y las restricciones.
Captura eficaz de datos: reduce la captura excesiva y la captura de datos inferiores

La API de GraphQL de Microsoft Fabric simplifica la integración de los lakehouses de Fabric, almacenes de datos y bases de datos con agentes de IA mediante una interfaz GraphQL estandarizada. Aunque LA API para GraphQL ya proporciona funcionalidades de consulta eficaces, la configuración de una conexión para agentes de IA podría no ser tan sencilla como podría ser.

Con un sencillo servidor MCP de GraphQL local, los desarrolladores pueden usar agentes de INTELIGENCIA ARTIFICIAL para detectar su estructura de datos de Fabric, comprender lo que está disponible y consultarlo mediante lenguaje natural, todo ello a través de la interfaz MCP estandarizada. Convenientemente, no es necesario definir una herramienta MCP independiente en el servidor para cada tipo, consulta o mutación de GraphQL. El servidor MCP de GraphQL inspecciona el esquema de GraphQL, lo que permite a los agentes de IA entender todos los tipos y operaciones disponibles desde el principio.

Prerrequisitos

Antes de comenzar este tutorial, asegúrese de que tiene:

Un área de trabajo de Microsoft Fabric con los permisos adecuados. Se necesita un rol de administrador del espacio de trabajo para configurar entidades de servicio y habilitar la introspección.
Una API para el elemento GraphQL creado y configurado. Consulte Creación y adición de datos a una API para GraphQL o Creación de GraphQL API desde la base de datos SQL en el portal de Fabric.
Node.js instalado en la máquina de desarrollo (incluye npm)
Visual Studio Code instalado en la máquina de desarrollo

Nota:

¿No es un administrador? Algunos pasos de este tutorial requieren permisos de administrador. Si no es administrador, puede completar la mayoría del tutorial pidiendo al administrador que le ayude con tareas específicas. Cada paso que requiere permisos de administrador está claramente marcado.

Paso 1: Configurar el acceso del principal de servicio

Lo que estás haciendo: Configurar credenciales de autenticación no interactivas para que el servidor MCP de GraphQL pueda acceder a Fabric sin necesidad de que un usuario inicie sesión cada vez.

Por qué esto importa: El servidor MCP de GraphQL se ejecuta como un servicio en segundo plano al que los agentes de IA llaman automáticamente. Necesita su propia identidad (una entidad de servicio) con credenciales para autenticarse en Fabric en nombre de la aplicación, no en nombre de un usuario específico.

Siga la guía completa en Uso de Principales de Servicio con Fabric API para GraphQL para:

Creación de un registro de aplicaciones de Azure (cualquier usuario con permisos para crear registros de aplicaciones en microsoft Entra ID)
Agregar un secreto de cliente en Certificados y secretos (cualquier usuario)
Habilitación de entidades de servicio en la configuración del inquilino (requiere el administrador de inquilinos de Fabric)
Conceder permisos a la API de GraphQL y al área de trabajo (requiere el rol de administrador o colaborador del área de trabajo)

Sugerencia

¿No es un administrador? Puede completar los dos primeros elementos usted mismo. Para la configuración de inquilino, pida al administrador de inquilinos de Fabric que habilite "Las entidades de servicio pueden usar las API de Fabric" en el portal de administración>Configuración de inquilinos>Configuración del desarrollador. Para los permisos de espacio de trabajo, solicite al administrador que conceda acceso al principal de servicio al espacio de trabajo o a una API de GraphQL específica.

Cuando complete la configuración, capture estos tres valores para la configuración del servidor MCP de GraphQL:

Id. de inquilino: se encuentra en Microsoft Entra ID en Información general>: Id. de inquilino
ID de cliente: se encuentra en el registro de aplicaciones en Información general>ID de aplicación (cliente)
Secreto de cliente: el valor del secreto que se muestra al crear un nuevo secreto de cliente (copiar inmediatamente, solo se muestra una vez).

Paso 2: Habilitar la introspección de GraphQL (requiere el administrador del área de trabajo)

Lo que estás haciendo: Habilitar la introspección permite que el servidor MCP de GraphQL pregunte a graphQL API "¿Qué datos tiene?" y reciba una descripción completa de todos los tipos, campos y relaciones disponibles.

Por qué esto importa: Esta es la "magia" que hace posible las consultas de lenguaje natural. Cuando se le pregunta a Copilot "Mostrarme clientes", el agente de IA usa primero la introspección para detectar que existe un customers tipo, qué campos tiene y cómo consultarlo. Sin la introspección, tendría que documentar manualmente todo el esquema de la inteligencia artificial.

Importante

La introspección debe estar habilitada para que el servidor MCP de GraphQL funcione. Esto está deshabilitado de forma predeterminada en Fabric por motivos de seguridad. Solo los administradores del área de trabajo pueden habilitar la introspección. Si no es administrador, pida al administrador del área de trabajo que complete este paso.

Siga la guía completa en Microsoft Fabric API for GraphQL Introspection and Schema Export para:

Habilitación de la introspección en la configuración de la API
Comprender cómo funcionan las consultas de introspección
Más información sobre las opciones de exportación de esquemas

Una vez habilitada la introspección, el servidor MCP de GraphQL puede consultar la estructura del esquema y ponerla a disposición de los agentes de IA.

Paso 3: Configurar el servidor MCP de GraphQL

Lo que estás haciendo: Instalación y configuración de un servidor Node.js local que implementa el Protocolo de contexto de modelo. Este servidor actúa como traductor entre agentes de IA y fabric GraphQL API.

Por qué esto importa: El servidor MCP proporciona una interfaz estandarizada que los agentes de IA entienden. Cuando un agente de IA se conecta, puede detectar qué herramientas están disponibles (introspección y consulta), llamar a esas herramientas y recibir respuestas, todo ello sin escribir código de integración personalizado para cada plataforma de INTELIGENCIA ARTIFICIAL.

Ahora que tiene credenciales de autenticación (paso 1) e introspección habilitadas (paso 2), está listo para configurar el servidor para usarlos.

Clonación del repositorio de ejemplo

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/MCP

Instalación de dependencias

npm install

Configuración de las variables de entorno

Cree un archivo .env en la raíz del proyecto con su configuración.

MICROSOFT_FABRIC_API_URL=https://your-fabric-endpoint/graphql
MICROSOFT_FABRIC_TENANT_ID=your_tenant_id_here
MICROSOFT_FABRIC_CLIENT_ID=your_client_id_here
MICROSOFT_FABRIC_CLIENT_SECRET=your_client_secret_here
SCOPE=https://api.fabric.microsoft.com/.default

Reemplace los valores de marcador de posición por:

MICROSOFT_FABRIC_API_URL: Tu punto de conexión de GraphQL desde el portal de Fabric
MICROSOFT_FABRIC_TENANT_ID: identificador de inquilino de Azure
MICROSOFT_FABRIC_CLIENT_ID: identificador de cliente de registro de aplicaciones
MICROSOFT_FABRIC_CLIENT_SECRET: secreto de cliente de registro de aplicaciones

Iniciar el servidor MCP de GraphQL

node FabricGraphQL_MCP.js

El servidor se inicia en http://localhost:3000 y muestra:

Microsoft Fabric GraphQL MCP server listening on port 3000
API URL: https://your-fabric-endpoint/graphql
Scope: https://api.fabric.microsoft.com/.default

Herramientas de MCP disponibles

El servidor MCP de GraphQL proporciona dos herramientas principales:

`introspect-schema`

Propósito: recupera el esquema de GraphQL completo.
Parámetros: ninguno
Uso: se debe llamar primero antes de realizar consultas.

`query-graphql`

Propósito: ejecuta consultas de GraphQL en los datos de Fabric
Parámetros:
- query (obligatorio): la cadena de consulta GraphQL
- variables (opcional): Objeto de variables GraphQL
Uso: para todas las operaciones de recuperación y manipulación de datos

Descripción del flujo de trabajo

El flujo de trabajo típico de GraphQL MCP sigue este patrón:

Detección de esquemas: el agente de IA debe llamar primero a la introspect-schema herramienta para comprender el esquema y los datos disponibles
Planeamiento de consultas: el agente analiza la solicitud de lenguaje natural y el esquema de GraphQL
Generación de consultas: el agente crea consultas de GraphQL adecuadas
Ejecución: el agente llama a la query-graphql herramienta con las consultas generadas.
Procesamiento de respuestas: el agente da formato y presenta los resultados

Paso 4: Probar el servidor MCP de GraphQL

Lo que estás haciendo: Comprobar que el servidor MCP puede autenticarse en Fabric, recuperar el esquema y ejecutar consultas, antes de conectar agentes de IA.

Por qué esto importa: Las pruebas se aseguran manualmente de que todo está configurado correctamente. Si se superan estas pruebas, sabe que los agentes de IA pueden conectarse correctamente en el paso 5.

Comprobación del estado del servidor

En primer lugar, confirme que el servidor se está ejecutando y puede autenticarse en Fabric.

Con PowerShell:

Invoke-RestMethod -Uri "http://localhost:3000/health" -Method Get

Uso de cURL:

curl http://localhost:3000/health

Debe recibir una respuesta que indique que el servidor se está ejecutando, de forma similar a:

{"status":"healthy","server":"Microsoft Fabric GraphQL MCP Server","hasToken":true,"tokenExpiry":"2025-06-30T23:11:36.339Z"}

Probar la introspección del esquema

A continuación, compruebe que el servidor puede recuperar el esquema de GraphQL a través de la introspección. Esto llama a la herramienta introspect-schema MCP.

Con PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/call"
    params = @{
        name = "introspect-schema"
        arguments = @{}
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Uso de cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {}
    }
  }'

Esto debe devolver la definición de esquema de GraphQL.

Prueba de una consulta de GraphQL

Por último, pruebe la ejecución de una consulta de GraphQL real a través del servidor MCP. En este ejemplo se consultan todos los nombres de tipo del esquema mediante la query-graphql herramienta MCP.

Con PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 2
    method = "tools/call"
    params = @{
        name = "query-graphql"
        arguments = @{
            query = "query { __schema { types { name } } }"
        }
    }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Uso de cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "query { __schema { types { name } } }"
      }
    }
  }'

Esto devuelve una lista de todos los tipos del esquema de GraphQL.

Paso 5: Conexión de agentes de IA

Lo que estás haciendo: Configuración de herramientas de inteligencia artificial para usar el servidor MCP local como origen de datos.

Por qué esto importa: Aquí es donde todo se reúne. Una vez conectado, los agentes de IA pueden detectar el esquema de Fabric a través de la introspección y generar consultas de GraphQL basadas en solicitudes de lenguaje natural. La inteligencia artificial se encarga de la sintaxis de la consulta. Solo tiene que hacer preguntas en inglés sencillo.

GitHub Copilot en Visual Studio Code

Instala la extensión de Copilot de GitHub en VS Code

Configure el servidor MCP de GraphQL en la configuración de Copilot:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

En el chat de Copilot, primero pida que introspecte el esquema y, a continuación, intente formular una pregunta pertinente relacionada con los datos introspectados en lenguaje natural, por ejemplo:

Cursor IDE

Abrir la configuración del cursor

Agregue la configuración del servidor MCP:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

En el chat, primero pida que introspecte el esquema y, a continuación, intente formular una pregunta pertinente relacionada con los datos introspectados en lenguaje natural.

Lo que ha creado

¡Felicidades! Ahora tiene un servidor MCP de GraphQL en funcionamiento que:

Se autentica en Fabric utilizando credenciales de entidad de servicio
Expone el esquema de datos de Fabric a través de la introspección
Traduce las solicitudes del agente de IA en consultas de GraphQL.
Devuelve datos en un formato que los agentes de IA pueden comprender y presentar

Los agentes de IA (como GitHub Copilot) ahora pueden:

Detectar automáticamente qué datos están disponibles en el área de trabajo de Fabric
Generación de consultas de GraphQL correctas basadas en preguntas de lenguaje natural
Recuperar y dar formato a los resultados sin escribir ningún código de consulta

Este servidor local está diseñado para el desarrollo y el aprendizaje. En las secciones siguientes se tratan consideraciones importantes para las implementaciones de producción y escenarios comunes de solución de problemas.

Consideraciones de seguridad

Aunque el servidor MCP de GraphQL local solo debe implementarse con fines de desarrollo, tal como se describe en este tutorial, se implementa con transporte HTTP, lo que facilita su uso como punto de partida para integraciones basadas en web o servidor cliente más complejas. Si va a implementar servidores MCP de GraphQL en producción:

Uso de Azure Key Vault para almacenar secretos en lugar de .env archivos
Implementación de reglas de firewall, seguridad de red y autorización adecuadas
Habilitación del registro de auditoría para todas las consultas de GraphQL
Uso de Azure App Service o Container Instances para hospedar
Implementación de la limitación de velocidad y autenticación para los puntos de conexión de MCP
Realizar regularmente la rotación de secretos y certificados de cliente

Solución de problemas

Problemas comunes y soluciones

Errores de autenticación

Comprobación de que el registro de aplicaciones de Azure tiene los permisos correctos
Compruebe que los principales de servicio están habilitados en su arrendatario de Fabric.
Asegúrese de que el secreto de cliente no ha expirado

Error de introspección de esquema

Confirmación de que la introspección está habilitada en la configuración de GraphQL API
Compruebe que la dirección URL del punto de conexión de GraphQL es correcta
Comprobación de la conectividad de red con el área de trabajo de Fabric

El agente de IA no reconoce las herramientas

Reinicio del cliente de IA después de los cambios de configuración
Compruebe que la dirección URL del servidor MCP sea accesible
Comprobación de los registros del servidor para ver los mensajes de error

Errores de ejecución de consultas

Revise la consola del servidor para ver las consultas registradas y los errores.
Asegúrese de que las consultas coinciden con el esquema disponible
Compruebe que tiene los permisos adecuados para los datos solicitados.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-01-21

Compartir a través de

Conexión de agentes de IA a Fabric API para GraphQL con un servidor de Protocolo de contexto de modelo local (MCP)

¿Cuál es el protocolo de contexto de modelo (MCP)?

Por qué GraphQL es ideal para MCP

Prerrequisitos

Paso 1: Configurar el acceso del principal de servicio

Paso 2: Habilitar la introspección de GraphQL (requiere el administrador del área de trabajo)

Paso 3: Configurar el servidor MCP de GraphQL

Clonación del repositorio de ejemplo

Instalación de dependencias

Configuración de las variables de entorno

Iniciar el servidor MCP de GraphQL

Herramientas de MCP disponibles

introspect-schema

query-graphql

Descripción del flujo de trabajo

Paso 4: Probar el servidor MCP de GraphQL

Comprobación del estado del servidor

Probar la introspección del esquema

Prueba de una consulta de GraphQL

Paso 5: Conexión de agentes de IA

GitHub Copilot en Visual Studio Code

Cursor IDE

Lo que ha creado

Consideraciones de seguridad

Solución de problemas

Problemas comunes y soluciones

Contenido relacionado

Comentarios

Recursos adicionales

`introspect-schema`

`query-graphql`