Model Context Protocol · .NET 9

Datalake-MCP

An MCP server that exposes an Azure Data Lake Storage Gen2 account to Claude: browse files and folders and extract data from CSV, Parquet, XML, text and markdown, with streaming reads and pagination built for scale.

What it does

The server authenticates against an Azure Data Lake Gen2 account (accountName/accountKey) and exposes, via the MCP protocol, a set of tools that let Claude browse the structure of the data lake and read file contents, applying filters, projections and pagination without ever loading a whole file into memory.

Navigation

Lists filesystems, folders and files, with metadata (size, last modified).

Multi-format reading

CSV, Parquet, tabular XML, text (.txt) and markdown (.md), each with its own reader.

Saving and search

Saves text, markdown, CSV, Parquet and PDF files, records them in an index and finds them again with search_file.

Efficient streaming

Streaming reads by row group/element, with lazy loading of bytes from the data lake.

Pagination

Every read stops at a row/line limit and returns a nextOffset to continue.

Architecture

The server is a .NET Generic Host over stdio transport, with a dedicated reader service for each format.

Claude → MCP (stdio) → Tools/DataLakeTools.cs → Reader Services → Azure Data Lake Gen2
FileResponsibility
Configuration/DataLakeOptions.csConnection options (AccountName / AccountKey / DefaultFileSystem)
Services/DataLakeService.csWrapper around Azure.Storage.Files.DataLake: navigation and streaming
Services/CsvReaderService.csRow-by-row CSV reading, with a row limit
Services/ParquetReaderService.csRow-group Parquet reading, with column projection
Services/TextReaderService.csLine-by-line reading of text/markdown files
Services/XmlReaderService.csElement-by-element reading of tabular XML, with column projection
Services/FileWriterService.csBuilds and validates the bytes to save (text, CSV, Parquet, PDF)
Services/FileIndex.csSaved-files CSV index: upsert, parsing and search
Tools/DataLakeTools.csMCP tools exposed to the client

Exposed MCP tools

Each tool is designed to be composed: first explore, then read the schema, finally extract the data page by page.

ToolDescription
list_filesystemsLists the account's filesystems (containers)
list_directoryLists files and directories in a path (optionally recursive)
get_file_infoFile metadata (size, last modified date)
create_folderCreates a folder in the filesystem root or as a subfolder of an existing folder (the parent must exist; error if the folder already exists)
read_csvReads a CSV, with maxRows, configurable delimiter, offset and a filter
get_parquet_schemaSchema (columns/types) of a Parquet file without reading its data
read_parquetReads a Parquet file, with maxRows, column projection, offset and a filter
read_textReads a text file (.txt), with maxLines, offset and a contains filter
read_markdownReads a markdown file (.md), with maxLines, offset and a contains filter
get_xml_schemaSchema (attributes/elements) of the record element of a tabular XML file
read_xmlReads a tabular XML file, with optional record element and columns, offset and a filter
save_textSaves a .txt file in a folder/subfolder of the data lake
save_markdownSaves a .md file
save_csvSaves a .csv file from CSV text (validated: same number of fields on every row)
save_parquetSaves a .parquet file from a list of rows (column → value objects); types are inferred
save_pdfSaves a .pdf file from base64 content (the %PDF- header is checked)
search_fileSearches the saved-files index by nomeFile (contains, case-insensitive) and/or tipoFile; if exactly one file matches, its content is returned too

Saving files and index

The save_* tools take path (missing folders are created), fileSystem, description and overwrite. Without overwrite=true an existing file is never replaced.

Every save is recorded in the index DataLake:SavedFilesIndexPath (default saved-files-index.csv at the filesystem root), a CSV readable with read_csv with columns path,name,format,sizeBytes,savedAt,description. Saving the same path again updates its row; the index is updated with optimistic concurrency (ETag, up to 5 attempts). search_file queries this index.

Pagination

Responses from the read tools are subject to the tool call size limit (about 1 MB). When a file exceeds maxRows/maxLines, the result reports truncated: true and a nextOffset.

  1. Call the tool with offset: 0.
  2. If truncated is true, call the same tool again with offset = nextOffset.
  3. Repeat until truncated is false (nextOffset will be null).

Configuration and running

Never commit account credentials: use .NET user-secrets during development.

dotnet user-secrets init
dotnet user-secrets set "DataLake:AccountName" "<account-name>"
dotnet user-secrets set "DataLake:AccountKey" "<account-key>"
dotnet user-secrets set "DataLake:DefaultFileSystem" "<default-container>"

dotnet build
dotnet test
dotnet run --project src/Datalake.Mcp.Server

The server communicates over stdio using the MCP protocol: it must be registered as an MCP server in the client (e.g. Claude Desktop / Claude Code). An example configuration is available in claude_desktop_config.example.json.

Model Context Protocol · .NET 9

Datalake-MCP

Un server MCP che espone un Azure Data Lake Storage Gen2 a Claude: naviga file e cartelle ed estrae dati da CSV, Parquet, XML, testo e markdown, con letture in streaming e paginazione pensate per la scala.

Cosa fa

Il server si autentica su un account Azure Data Lake Gen2 (accountName/accountKey) ed espone via protocollo MCP un set di tool che permettono a Claude di navigare la struttura del datalake e leggere il contenuto dei file, applicando filtri, proiezioni e paginazione senza mai caricare un intero file in memoria.

Navigazione

Elenca filesystem, cartelle e file, con metadati (dimensione, ultima modifica).

Lettura multi-formato

CSV, Parquet, XML tabellare, testo (.txt) e markdown (.md), ciascuno con il proprio reader.

Salvataggio e ricerca

Salva file testo, markdown, CSV, Parquet e PDF, li registra in un indice e li ritrova con search_file.

Streaming efficiente

Lettura in streaming e a row-group/elemento, con caricamento differito dei byte dal datalake.

Paginazione

Ogni lettura si ferma a un limite di righe/linee e restituisce un nextOffset per proseguire.

Architettura

Il server è un host .NET Generic Host su trasporto stdio, con un servizio di reader dedicato per ogni formato.

Claude → MCP (stdio) → Tools/DataLakeTools.cs → Reader Services → Azure Data Lake Gen2
FileResponsabilità
Configuration/DataLakeOptions.csOpzioni di connessione (AccountName / AccountKey / DefaultFileSystem)
Services/DataLakeService.csWrapper su Azure.Storage.Files.DataLake: navigazione e streaming
Services/CsvReaderService.csLettura CSV riga per riga, con limite di righe
Services/ParquetReaderService.csLettura Parquet a row-group, con proiezione colonne
Services/TextReaderService.csLettura file di testo/markdown riga per riga
Services/XmlReaderService.csLettura XML tabellare elemento per elemento, con proiezione colonne
Services/FileWriterService.csCostruzione e validazione dei byte da salvare (testo, CSV, Parquet, PDF)
Services/FileIndex.csIndice CSV dei file salvati: upsert, parsing e ricerca
Tools/DataLakeTools.csTool MCP esposti al client

Tool MCP esposti

Ogni tool è pensato per essere composto: prima si esplora, poi si legge lo schema, infine si estraggono i dati a pagine.

ToolDescrizione
list_filesystemsElenca i filesystem (container) dell'account
list_directoryElenca file e directory in un percorso (opzionalmente ricorsivo)
get_file_infoMetadati di un file (dimensione, data ultima modifica)
create_folderCrea una cartella nella radice del filesystem o come sottocartella di una cartella esistente (il padre deve esistere; errore se la cartella esiste già)
read_csvLegge un CSV, con maxRows, delimitatore configurabile e offset e filtro filter
get_parquet_schemaSchema (colonne/tipi) di un Parquet senza leggerne i dati
read_parquetLegge un Parquet, con maxRows, proiezione colonne e offset e filtro filter
read_textLegge un file di testo (.txt), con maxLines e offset e filtro contains
read_markdownLegge un file markdown (.md), con maxLines e offset e filtro contains
get_xml_schemaSchema (attributi/elementi) dell'elemento record di un XML tabellare
read_xmlLegge un XML tabellare, con elemento record e colonne opzionali, e offset e filtro filter
save_textSalva un file .txt in una cartella/sottocartella del datalake
save_markdownSalva un file .md
save_csvSalva un file .csv da testo CSV (validato: stesso numero di campi per riga)
save_parquetSalva un file .parquet da un elenco di righe (oggetti colonna → valore); i tipi sono dedotti
save_pdfSalva un file .pdf da contenuto base64 (verificata l'intestazione %PDF-)
search_fileCerca nell'indice dei file salvati per nomeFile (contiene, case-insensitive) e/o tipoFile; se trova un solo file ne restituisce anche il contenuto

Salvataggio file e indice

I tool save_* accettano path (le cartelle mancanti vengono create), fileSystem, description e overwrite. Senza overwrite=true un file esistente non viene mai sostituito.

Ogni salvataggio viene registrato nell'indice DataLake:SavedFilesIndexPath (default saved-files-index.csv, nella radice del filesystem), un CSV leggibile con read_csv con colonne path,name,format,sizeBytes,savedAt,description. Salvare di nuovo lo stesso percorso aggiorna la riga; l'indice è aggiornato con concurrency ottimistica (ETag, fino a 5 tentativi). search_file interroga questo indice.

Paginazione

Le risposte dei tool di lettura sono soggette al limite di dimensione dei tool call (circa 1 MB). Quando un file eccede maxRows/maxLines, il risultato riporta truncated: true e un nextOffset.

  1. Chiama il tool con offset: 0.
  2. Se truncated è true, richiama lo stesso tool con offset = nextOffset.
  3. Ripeti finché truncated non è false (nextOffset sarà null).

Configurazione ed esecuzione

Le credenziali dell'account non vanno mai committate: usa i .NET user-secrets in sviluppo.

dotnet user-secrets init
dotnet user-secrets set "DataLake:AccountName" "<nome-account>"
dotnet user-secrets set "DataLake:AccountKey" "<chiave-account>"
dotnet user-secrets set "DataLake:DefaultFileSystem" "<container-predefinito>"

dotnet build
dotnet test
dotnet run --project src/Datalake.Mcp.Server

Il server comunica via stdio secondo il protocollo MCP: va registrato come server MCP nel client (es. Claude Desktop / Claude Code). Un esempio di configurazione è disponibile in claude_desktop_config.example.json.