Getting Started with Indexes MCP

This guide shows how to connect an MCP client to the hosted CoinAPI Indexes MCP server.

Endpoint and authentication

• MCP endpoint: https://mcp.indexes.coinapi.io/mcp
• Header: X-CoinAPI-Key: YOUR_API_KEY
• Transport: HTTP streaming MCP
• Supported path: Only /mcp

Cursor example

Add the Indexes server to your MCP client configuration:

{
  "mcpServers": {
    "CoinAPI-Indexes": {
      "url": "https://mcp.indexes.coinapi.io/mcp",
      "headers": {
        "X-CoinAPI-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your real API key and restart the client if required by your MCP application.

First requests to try

1. List available indexes

Call indexes_list with no arguments.

Example response excerpt:

[
  { "id": "IDX_MULTIASSET_TEST" },
  { "id": "IDX_REFRATE_FX_AED" },
  { "id": "IDX_REFRATE_FX_EUR" },
  { "id": "IDX_REFRATE_FX_GBP" },
  { "id": "IDX_REFRATE_FX_USD" }
]

2. List supported periods

Call periods_list with no arguments.

Example response excerpt:

[
  { "period_id": "1SEC", "display_name": "1 Second" },
  { "period_id": "1MIN", "display_name": "1 Minute" },
  { "period_id": "1HRS", "display_name": "1 Hour" },
  { "period_id": "1DAY", "display_name": "1 Day" },
  { "period_id": "1YRS", "display_name": "1 Year" }
]

3. Fetch the current value of one index

Call indexes_get_current with:

{
  "index_id": "IDX_REFRATE_FX_USD"
}

Example response:

{
  "timestamp": "2026-04-07T14:05:38.7",
  "value": 1
}

4. Fetch a full current snapshot for one index definition

Call indexes_get_current_snapshot with:

{
  "index_definition_id": "IDX_REFRATE_FX"
}

Example response excerpt:

[
  {
    "index_id": "IDX_REFRATE_FX_USD",
    "timestamp": "2026-04-07T14:05:29.1",
    "value": 1
  },
  {
    "index_id": "IDX_REFRATE_FX_EUR",
    "timestamp": "2026-04-07T14:05:29.1",
    "value": 1.155705
  }
]

5. Fetch historical values with composition

Call indexes_get_history with:

{
  "index_id": "IDX_REFRATE_FX_USD",
  "limit": 2
}

Example response excerpt:

[
  {
    "timestamp": "2026-04-07T14:05:01Z",
    "value": 1,
    "composition": []
  },
  {
    "timestamp": "2026-04-07T14:05:00Z",
    "value": 1,
    "composition": [
      {
        "component_id": "USD_USD_24H_AVERAGE_PRICE",
        "component_value": 1
      }
    ]
  }
]

6. Fetch OHLC timeseries

Call indexes_get_timeseries with:

{
  "index_id": "IDX_REFRATE_FX_USD",
  "period_id": "1DAY",
  "limit": 2
}

Example response excerpt:

[
  {
    "time_period_start": "2026-04-07T00:00:00Z",
    "time_period_end": "2026-04-08T00:00:00Z",
    "value_open": 1,
    "value_high": 1,
    "value_low": 1,
    "value_close": 1
  },
  {
    "time_period_start": "2026-04-06T00:00:00Z",
    "time_period_end": "2026-04-07T00:00:00Z",
    "value_open": 1,
    "value_high": 1,
    "value_low": 1,
    "value_close": 1
  }
]

7. Inspect multi-asset weights

Call multiasset_get_weights with:

{
  "index_id": "IDX_MULTIASSET_TEST"
}

Example response:

[
  { "indexId": "IDX_MULTIASSET_TEST", "assetId": "BTC", "weight": 2 },
  { "indexId": "IDX_MULTIASSET_TEST", "assetId": "ETH", "weight": 1 }
]

Recommended workflows

Current snapshot workflow

1. Call indexes_list.
2. Choose an index definition family such as IDX_REFRATE_FX.
3. Call indexes_get_current_snapshot to discover members that currently have values.
4. Call indexes_get_current for one specific index_id when you want a compact single-value response.

Historical analysis workflow

1. Call periods_list.
2. Use indexes_get_history when you need point history with composition.
3. Use indexes_get_history_snapshot when you need all members of one definition at a specific timestamp.
4. Use indexes_get_timeseries when you need OHLC data for charting.

Multi-asset administration workflow

1. Call multiasset_list_weights to inspect all stored weights.
2. Call multiasset_get_weights for one target index.
3. Use multiasset_update_weights and multiasset_delete_weights only in an authorized administrative context.

Troubleshooting

No tools appear in the client

• Verify the endpoint URL is exactly https://mcp.indexes.coinapi.io/mcp.
• Confirm the request includes the X-CoinAPI-Key header.
• Restart the MCP client after editing its configuration.

A listed index does not return a current value

• Start with indexes_get_current_snapshot on the parent definition to discover members that currently have data.
• Confirm the index_id spelling exactly matches one of the IDs returned by indexes_list.
• Some identifiers may exist in the catalog but not return a value at the exact moment you query them.

Timeseries returns fewer rows than expected

• Check whether your time_start, time_end, and limit combination actually permits the expected number of candles.
• Confirm the selected period_id exists in periods_list.
• Remember that sparse or inactive indexes may produce fewer populated intervals than a naive range calculation suggests.