Learn how to connect to CoinAPI's hosted Flat Files MCP server and use it to discover buckets, prefixes, and file keys.

Getting Started with CoinAPI Flat Files MCP

Summary

Learn how to connect to CoinAPI's hosted Flat Files MCP server and use it to discover buckets, dataset prefixes, and concrete object keys before downloading files through the S3 API.

What you'll learn

How to configure an MCP client with your CoinAPI API key
How to verify that the Flat Files MCP server is available
How to list the available buckets and browse prefixes
How to hand off discovered object keys to the standard S3 API

Step 1: Get your CoinAPI API key

Sign in to CoinAPI Console.
Create or copy a valid API key.
Make sure your account has Flat Files access and available usage credits.

To use Flat Files, add usage credits in the customer portal before listing or downloading files.

Step 2: Configure your MCP client

Cursor example

{
  "mcpServers": {
    "CoinAPI-Flat-Files": {
      "url": "https://mcp.flatfiles.coinapi.io/mcp",
      "headers": {
        "X-CoinAPI-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual CoinAPI API key, save the configuration, and restart your MCP client if required.

Connection details

URL: https://mcp.flatfiles.coinapi.io/mcp
Header: X-CoinAPI-Key: YOUR_API_KEY
Transport: HTTP streaming

Step 3: Verify the connection

Once connected, your MCP client should expose two Flat Files tools:

storage_list_buckets
storage_list_objects

Start with a simple discovery request:

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

Live-tested output currently includes both buckets:

{
  "buckets": [
    {
      "name": "coinapi",
      "bucketRegion": "us-east-1"
    },
    {
      "name": "coinapi-daily-tail",
      "bucketRegion": "us-east-1"
    }
  ]
}

Step 4: Discover top-level datasets in `coinapi`

Use the coinapi bucket for longer historical access and OHLCV:

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

Live-tested top-level prefixes currently include:

T-TRADES/
T-QUOTES/
T-LIMITBOOK_FULL/
T-OHLCV_ACTIVE_CONSOLIDATED/

These are folder-style prefixes returned in commonPrefixes.

Step 5: Inspect the previous day's daily data in `coinapi-daily-tail`

The coinapi-daily-tail bucket holds Trades, Quotes, and Full Limit Order Book files for the previous day only (24-hour retention). The date directory always reflects yesterday's date in YYYYMMDD format. This bucket is not a historical archive—legacy daily files published before 2026-06-09 remain in coinapi—and OHLCV is not published here.

To inspect the daily partition for trades:

{
  "tool": "storage_list_objects",
  "arguments": {
    "bucket": "coinapi-daily-tail",
    "prefix": "T-TRADES/"
  }
}

Live-tested results currently include a single daily partition for yesterday's date, such as:

T-TRADES/D-20260609/

Step 6: Drill into hourly partitions in `coinapi`

Starting from 2026-06-09, new Trades, Quotes, and Full Limit Order Book data in coinapi is published as hourly partitions (D-YYYYMMDDHH). Daily partitions published before that date remain in coinapi under D-YYYYMMDD and are not moved to coinapi-daily-tail.

To inspect available hourly partitions under trades:

{
  "tool": "storage_list_objects",
  "arguments": {
    "bucket": "coinapi",
    "prefix": "T-TRADES/"
  }
}

Live-tested results currently include hourly partitions such as:

T-TRADES/D-2026040712/
T-TRADES/D-2026040711/
T-TRADES/D-2026040710/

Continue narrowing the prefix until the response starts returning objects in contents instead of only folders in commonPrefixes.

Step 7: Download files through the S3 API

Flat Files MCP is intended for discovery, not byte downloads. Once you identify the object key you need, use the regular S3 API to list or download the file contents.