Conecta agentes de IA al servidor MCP alojado de OneLake (vista previa)

El servidor OneLake Model Context Protocol (MCP) alojado permite a los agentes de IA navegar por archivos, inspeccionar metadatos de tablas y gestionar directorios en un elemento Fabric sin instalar un servidor MCP local. Conecta un cliente compatible con MCP al punto final HTTPS del ítem, luego utiliza peticiones en lenguaje natural o llama directamente a las herramientas.

El servidor alojado proporciona una conexión del plano de datos del ítem y es una alternativa al servidor local Fabric MCP. Para la gestión de espacios de trabajo y elementos, atajos de OneLake y roles de acceso a datos de OneLake, utiliza el servidor MCP de Fabric Core. Conéctate a cada servidor para las operaciones que necesitas.

Prerequisites

• Un elemento Fabric que almacena datos en OneLake, con un endpoint OneLake MCP alojado disponible en tu entorno.
• Una identidad Microsoft Entra con permiso para realizar las operaciones previstas sobre los datos del artículo.
• Un cliente MCP que soporta HTTP Streamable y puede adjuntar un token al portador de Microsoft Entra a las solicitudes.
• Acceso a la red al punto final MCP y, para transferencias directas de archivos, al punto final de almacenamiento devuelto.

Para el modelo de permisos, véase Seguridad de datos en OneLake. El acceso al espacio de trabajo por sí solo no significa que cada identidad pueda leer o escribir todas las rutas de datos. Para los requisitos de redes, consulta Conectar a OneLake.

Conectar a un elemento

Utiliza la URL alojada del endpoint OneLake MCP para tu espacio de trabajo y el elemento.

1. Añade la URL a la configuración HTTP MCP de tu cliente. Configura la autenticación como se describe en la siguiente sección y luego inicializa la conexión.
2. Pide al agente que llame a onelake_list_items_data para descubrir las áreas de datos de mayor nivel del elemento sin cambiar los datos. Elige un directorio retornado para explorar con onelake_list_files, usando un path relativo al elemento. No asumas que cada elemento tiene un directorio Files.

Para ubicaciones de instalación y configuración de Visual Studio Code, véase Añadir servidores MCP en VS Code. La configuración de autenticación depende del entorno del cliente y del agente; añadir una URL no inicia sesión.

El endpoint del elemento tiene esta ruta:

POST {oneLakeHost}/v1.0/workspaces/{workspaceId}/items/{itemId}/mcp

Aquí, {oneLakeHost} es el origen HTTPS de la URL de tu endpoint, y los dos IDs identifican el espacio de trabajo y el elemento. Mantén juntos el nombre de host y la ruta del endpoint. No sustituyas un nombre de host regional o específico del entorno por otro de OneLake diferente.

Utiliza un punto final identificado por GUID. Los nombres amigables están disponibles como argumentos de herramienta, tal y como se describe en Parámetros comunes. Una URL direccionada por nombre puede inicializarse con éxito, pero falla cuando una herramienta utiliza su contexto de URL.

Autenticación y permisos

Utiliza un token de acceso de Microsoft Entra para el recurso de Azure Storage, https://storage.azure.com/. Para bibliotecas de autenticación que aceptan scopes, utilice https://storage.azure.com/.default. No sustituyas un token por https://api.fabric.microsoft.com/.

Envía el token en la Authorization: Bearer <access-token> cabecera de cada solicitud. Para la configuración de la autenticación, consulte Prepararse para la autenticación.

El cliente es responsable de obtener y actualizar su token. Iniciar sesión en CLI de Azure no autentica automáticamente un cliente HTTP MCP arbitrario. Utiliza el mecanismo de credenciales soportado por tu cliente y no pongas tokens en chat, archivos de configuración compartidos ni control de versiones.

OneLake evalúa los permisos del llamante para cada operación. Conectar a un agente no le otorga acceso adicional a datos. Mantén activada la aprobación del usuario para escrituras y eliminaciones, y revisa el elemento y la ruta objetivo antes de aprobarlos.

Conexión y descubrimiento de MCP

El endpoint utiliza JSON-RPC 2.0 sobre HTTP Streamable. Cada mensaje MCP es un HTTP POST separado al mismo punto final.

Inicializa la conexión con la versión del protocolo soportada por tu cliente y luego envía notifications/initialized. El servidor negocia la versión 2025-06-18 del protocolo y se identifica como microsoft.onelake, versión 1.0.0. Sus capacidades incluyen logging y tools, con tools.listChanged: true. Utiliza los valores negociados en lugar de codificar directamente la versión del servidor.

Descubre las herramientas con esta petición:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Lee el name, description, inputSchema y annotations de cada entrada. Si una respuesta incluye result.nextCursor, pásala como params.cursor para obtener la siguiente página. Actualiza el descubrimiento cuando el servidor envíe notifications/tools/list_changed.

El catálogo descrito aquí contiene 15 herramientas: 11 marcadas como solo lectura e idempotentes, y cuatro marcadas como destructivas. Las anotaciones de herramientas describen el comportamiento; no son concesiones de permiso. El servidor no anuncia un outputSchema para estas herramientas.

Referencia de herramientas

Utiliza los nombres exactos de las herramientas y el uso de mayúsculas y minúsculas de los parámetros que devuelve tools/list. Las siguientes tablas cubren todos los parámetros de este catálogo. Descubre los schemas actuales al conectarte, porque las herramientas disponibles pueden cambiar. Las herramientas de archivos utilizan la API de sistema de archivos distribuido (DFS) o API Blob de OneLake.

Parámetros comunes

Cada herramienta acepta estos parámetros opcionales además de sus parámetros específicos de cada herramienta:

Normalmente, se omiten ambos parámetros para trabajar con el elemento de la URL. Cuando especifiques explícitamente un objetivo, usa ambos GUIDs o ambos nombres. El alcance de URL proporciona valores predeterminados; no elimina estos parámetros de segmentación ni reemplaza la autorización.

Los esquemas declaran estos parámetros como cadenas con un valor de null en default. Omita una cadena opcional para usar el valor predeterminado en lugar de enviar JSON null: null no se incluye en su tipo declarado. Esta regla también se aplica a path, prefix, schemaName, y contentType donde esas cadenas son opcionales.

Las rutas de archivo y directorio son relativas al elemento, como Files/incoming/orders.csv o Tables/dbo/orders. No incluyas el espacio de trabajo ni el identificador del objeto en un argumento path.

Navega y lee datos

El servidor marca estas herramientas como solo lectura e idempotentes.

Empieza con un filtro estrecho path o prefix. Los listados recursivos y los listados Blob amplios pueden producir más datos de los que un agente necesita.

Inspeccionar metadatos de la tabla

El servidor marca estas herramientas como solo lectura e idempotentes. Inspeccionan metadatos, no filas de tabla.

Utiliza un espacio de nombres devuelto por onelake_list_namespaces en lugar de asumir que todos los elementos tienen los mismos esquemas. Para las APIs subyacentes, véase las APIs de tablas de OneLake.

Obtener instrucciones para transferir archivos

El servidor marca estas herramientas como solo lectura e idempotentes. Devuelven instrucciones pero no transfieren bytes de archivo. Ejecutar una instrucción de subida es una operación de escritura separada.

Usa onelake_get_upload_instructions para cargar un archivo. El catálogo no incluye una herramienta de subida en línea, aunque la descripción de la herramienta de instrucciones de subida se refiere a uploadFile. De manera similar, utiliza el nombre anunciado onelake_download_file, no la abreviatura downloadFile en la descripción de la herramienta de instrucciones de descarga.

Un resultado de instrucción de subida incluye un bloque de contenido resource_link. Su uri es el destino, e _meta incluye method, tokenAudience, path y overwrite. El resultado también incluye orientación textual. El enlace no contiene los bytes del archivo ni permite acceder al destino.

Autentica la transferencia por separado para la audiencia devuelta. Antes de ejecutar un comando, comprueba su destino y el comportamiento de sobrescritura. El texto generado puede contener un nombre de host que difiere del enlace del recurso, o indicar que un archivo pequeño supera el límite en línea. No ejecutes instrucciones contradictorias tal cual; verifica el destino con la información de conexión de almacenamiento del objeto.

Crear y eliminar directorios o archivos

El servidor marca estas cuatro herramientas como destructivas. Requiere confirmación antes de invocarlos.

Las descripciones de las herramientas advierten que la eliminación de archivos y blobs es irreversible. No utilices estas herramientas para eliminar archivos de una tabla como sustituto de una operación de mantenimiento consciente de la tabla.

Ver resultados de la herramienta

Una llamada a una herramienta MCP devuelve un JSON-RPC result con un content array. Inspecciona el type de cada bloque; no asumas que cada herramienta devuelve un objeto JSON directamente.

Gestiona tanto las respuestas HTTP JSON como las respuestas text/event-stream. Para lo segundo, procesa los mensajes JSON-RPC transportados por eventos enviados por el servidor. Consulta los resultados de la herramienta MCP.

Las cargas útiles de metadatos tienen diferentes formas:

• Los listados DFS devuelven Paths, un array de objetos, y pueden incluir ContinuationToken, que puede ser null. Cada camino incluye Name (cadena), IsDirectory (booleana), ContentLength (entera), LastModified (cadena), ETag (cadena), Owner (cadena) y Permissions (cadena).
• Los listados de blobs devuelven un Blobs array. Las entradas incluyen Name, ContentLength, ContentType, LastModified, ETag, y el booleano IsPrefix. Una cadena vacía ContentType es una cadena, no null.
• Los listados de espacios de nombres devuelven namespaces como un array de matrices de cadenas, como [["dbo"]], y pueden incluir next-page-token.
• Los detalles del espacio de nombres regresan namespace como una cadena, exists como un valor booleano y tables una cadena codificada en JSON. Analiza tables por separado para inspeccionar la lista de tablas anidadas.
• Los resultados de acceso incluyen workspaceId, itemId, las banderas booleanas canRead, canWrite, y canExecute, más campos owner de cadena y permissions. Estas cadenas pueden estar vacías.

Preservar el uso de mayúsculas y minúsculas del campo y distinguir propiedades omitidas, null, cadenas vacías y arrays vacíos. Procesa los campos que tu cliente entiende sin rechazar una respuesta completa cuando aparezcan campos adicionales.

Ejemplo: explorar los archivos de un elemento

Después de conectarte a un lakehouse y confirmar que onelake_list_items_data devuelve un directorio Files, pregunta a tu agente:

"Enumera los directorios bajo Archivos en este ítem. No cambies ningún dato."

La llamada a la herramienta correspondiente es:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "onelake_list_files",
    "arguments": {
      "path": "Files",
      "recursive": false
    }
  }
}

A continuación se muestra el JSON completo decodificado desde el primer result.content[].text bloque de la respuesta, no el sobre JSON-RPC. Los IDs de los artículos y propietarios, los nombres de directorios, las marcas de tiempo y los ETags son ilustrativos.

{
  "Paths": [
    {
      "Name": "87654321-4321-4321-8321-cba987654321/Files/incoming",
      "IsDirectory": true,
      "ContentLength": 0,
      "LastModified": "Wed, 21 Oct 2026 10:00:00 GMT",
      "ETag": "0x8DE000000000001",
      "Owner": "11111111-2222-4333-8444-555555555555",
      "Permissions": "rwxr-x---"
    },
    {
      "Name": "87654321-4321-4321-8321-cba987654321/Files/archive",
      "IsDirectory": true,
      "ContentLength": 0,
      "LastModified": "Tue, 20 Oct 2026 10:00:00 GMT",
      "ETag": "0x8DE000000000002",
      "Owner": "11111111-2222-4333-8444-555555555555",
      "Permissions": "rwxr-x---"
    }
  ],
  "ContinuationToken": null
}

Ambas entradas son directorios. Sus ContentLength valores no representan el tamaño total de los archivos que tienen debajo. Para explorar el primer directorio, llama onelake_list_files con path: "Files/incoming". El valor devuelto Name incluye el ID del artículo, pero el path de la siguiente herramienta es relativo al artículo.

Otras tareas que puedes pedir a tu agente que realice incluyen:

• Lista los espacios de nombres en este lakehouse y luego muestra los metadatos de una tabla que yo seleccione.
• Lee el archivo de configuración JSON en Files/config/settings.json.
• Obtén instrucciones de descarga para Files/exports/orders.parquet. No lo transfieras todavía."

Errores y limitaciones

Comprobar el estado HTTP, un JSON-RPC errorde nivel superior, y result.isError. HTTP 200 por sí solo no significa que una herramienta haya tenido éxito.

Por ejemplo, un archivo perdido puede devolver esta respuesta completa JSON-RPC:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The requested path or resource was not found."
      }
    ],
    "isError": true
  },
  "id": 27,
  "jsonrpc": "2.0"
}

Limitaciones adicionales:

• Los listados de almacenamiento y tablas no exponen los parámetros de entrada del token de continuación en este catálogo. No des por hecho que un listado es exhaustivo cuando alcanza un límite o devuelve un token de continuación. Utiliza las APIs de archivos de OneLake o APIs de tablas subyacentes cuando necesites paginación.
• maxResults limita un listado de Blob; no es un cursor de paginación.

Contenido relacionado

• Referencia de herramientas del servidor MCP de Fabric Core.
• Usa el servidor local de Fabric MCP con OneLake.
• Conectarse a OneLake.
• Visión general de las APIs de tablas de OneLake.
• Seguridad de datos en OneLake.