Flat Files MCP Tool Reference

The Flat Files MCP server currently exposes 2 tools.

Bucket discovery

storage_list_buckets

List all storage buckets available to the authenticated API key.

Arguments

This tool does not require any arguments.

Returns

The response includes:

• buckets, an array of bucket objects
• owner, metadata about the bucket owner

Each bucket item can include fields such as:

• name
• creationDate
• bucketRegion

Use when

• You want to confirm which buckets are visible to the current API key.
• You need the bucket name before calling storage_list_objects.
• You want to validate MCP connectivity with the simplest possible request.

Object and prefix discovery

storage_list_objects

List objects in a bucket with an optional prefix filter. The response follows an S3-style layout and can represent either folder-like prefixes or concrete files.

Required arguments

Optional arguments

Returns

Depending on the requested level, the response can include:

• isTruncated
• contents
• prefix
• maxKeys
• commonPrefixes
• delimiter
• keyCount
• contentLength
• httpStatusCode

When contents is present, each item can include:

• key
• lastModified
• size

When commonPrefixes is present, each item includes:

• prefix

Use when

• You want to inspect the bucket hierarchy without downloading files.
• You need to discover exchange identifiers such as E-IEXG/ or E-XWAR/.
• You want to enumerate dataset families such as T-OHLCV+TP-1DAY/.
• You need file metadata like object key, last modified timestamp, and size before downloading through S3.

Practical examples

Example: list all accessible buckets

{
  "tool": "storage_list_buckets",
  "arguments": {}
}

Example: list top-level exchange prefixes

{
  "tool": "storage_list_objects",
  "arguments": {
    "bucket": "finfeedapi"
  }
}

This typically returns commonPrefixes such as:

• E-IEXG/
• E-XWAR/
• E-XHKG/

Example: list datasets for one exchange

{
  "tool": "storage_list_objects",
  "arguments": {
    "bucket": "finfeedapi",
    "prefix": "E-IEXG/"
  }
}

Live-tested results currently include:

• E-IEXG/T-OHLCV+TP-1SEC/
• E-IEXG/T-OHLCV+TP-1MIN/
• E-IEXG/T-OHLCV+TP-1DAY/

Example: list object files inside one dataset prefix

{
  "tool": "storage_list_objects",
  "arguments": {
    "bucket": "finfeedapi",
    "prefix": "E-IEXG/T-OHLCV+TP-1DAY/"
  }
}

Example response excerpt:

{
  "contents": [
    {
      "key": "E-IEXG/T-OHLCV+TP-1DAY/D-20161212.csv.gz",
      "lastModified": "2025-06-18T22:51:50.994Z",
      "size": 187642
    }
  ]
}

Usage guidance

• Start with storage_list_buckets, then pass the discovered bucket name into storage_list_objects.
• Use broader prefixes first and narrow them gradually instead of guessing full file keys.
• Expect folder-like results to appear in commonPrefixes and actual files to appear in contents.
• Keep the trailing slash when browsing hierarchical prefixes, for example E-IEXG/.
• Use MCP for discovery and the standard S3 API for file downloads.