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.
| File | Responsibility |
|---|---|
Configuration/DataLakeOptions.cs | Connection options (AccountName / AccountKey / DefaultFileSystem) |
Services/DataLakeService.cs | Wrapper around Azure.Storage.Files.DataLake: navigation and streaming |
Services/CsvReaderService.cs | Row-by-row CSV reading, with a row limit |
Services/ParquetReaderService.cs | Row-group Parquet reading, with column projection |
Services/TextReaderService.cs | Line-by-line reading of text/markdown files |
Services/XmlReaderService.cs | Element-by-element reading of tabular XML, with column projection |
Services/FileWriterService.cs | Builds and validates the bytes to save (text, CSV, Parquet, PDF) |
Services/FileIndex.cs | Saved-files CSV index: upsert, parsing and search |
Tools/DataLakeTools.cs | MCP 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.
| Tool | Description |
|---|---|
list_filesystems | Lists the account's filesystems (containers) |
list_directory | Lists files and directories in a path (optionally recursive) |
get_file_info | File metadata (size, last modified date) |
create_folder | Creates 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_csv | Reads a CSV, with maxRows, configurable delimiter, offset and a filter |
get_parquet_schema | Schema (columns/types) of a Parquet file without reading its data |
read_parquet | Reads a Parquet file, with maxRows, column projection, offset and a filter |
read_text | Reads a text file (.txt), with maxLines, offset and a contains filter |
read_markdown | Reads a markdown file (.md), with maxLines, offset and a contains filter |
get_xml_schema | Schema (attributes/elements) of the record element of a tabular XML file |
read_xml | Reads a tabular XML file, with optional record element and columns, offset and a filter |
save_text | Saves a .txt file in a folder/subfolder of the data lake |
save_markdown | Saves a .md file |
save_csv | Saves a .csv file from CSV text (validated: same number of fields on every row) |
save_parquet | Saves a .parquet file from a list of rows (column → value objects); types are inferred |
save_pdf | Saves a .pdf file from base64 content (the %PDF- header is checked) |
search_file | Searches 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.
- Call the tool with
offset: 0. - If
truncatedistrue, call the same tool again withoffset = nextOffset. - Repeat until
truncatedisfalse(nextOffsetwill benull).
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.