{
  "base_url": "https://energy-api.com/api/v1",
  "mcp_endpoint": "POST https://mcp.energy-api.com/mcp",
  "tools": [
    {
      "name": "symbols",
      "method": "GET",
      "path": "/symbols",
      "description": "Full catalog of available price symbols, with name, category, country, currency, frequency, and description for each.",
      "params": [
        {
          "name": "category",
          "required": false,
          "description": "Filter by category: gas, electricity, carbon, carbon_intensity, coal, oil."
        },
        {
          "name": "provider",
          "required": false,
          "description": "Filter by upstream data provider: omie, fred, eex, eia, ember, electricity_maps, nasdaq, entsoe, esios, energy_charts, gridstatus, aemo."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code, e.g. EUR, USD. Filters to symbols priced in that currency."
        }
      ],
      "auth_required": true
    },
    {
      "name": "latest",
      "method": "GET",
      "path": "/latest",
      "description": "Most recent price for one or more symbols.",
      "params": [
        {
          "name": "symbols",
          "required": true,
          "description": "Comma-separated symbol codes, e.g. BRENT_CRUDE,TTF_GAS,EUA_CO2."
        },
        {
          "name": "category",
          "required": false,
          "description": "Filter by category instead of/in addition to symbols: gas, electricity, carbon, carbon_intensity, coal, oil."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "historical",
      "method": "GET",
      "path": "/historical",
      "description": "Price for one or more symbols on a specific past date. Falls back to the most recent value on or before that date for daily symbols (e.g. weekends/holidays); monthly symbols use the last value published within that month.",
      "params": [
        {
          "name": "date",
          "required": true,
          "description": "Y-m-d, e.g. 2025-09-12."
        },
        {
          "name": "symbols",
          "required": true,
          "description": "Comma-separated symbol codes."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "timeseries",
      "method": "GET",
      "path": "/timeseries",
      "description": "Historical price series between two dates for one or more symbols. The max date range is limited by the plan (see account plan tiers on the website); requests beyond it return 422.",
      "params": [
        {
          "name": "start",
          "required": true,
          "description": "Y-m-d."
        },
        {
          "name": "end",
          "required": true,
          "description": "Y-m-d, must be on or after start."
        },
        {
          "name": "symbols",
          "required": true,
          "description": "Comma-separated symbol codes."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "fluctuation",
      "method": "GET",
      "path": "/fluctuation",
      "description": "Percent change, minimum, and maximum price over a date range, per symbol.",
      "params": [
        {
          "name": "start",
          "required": true,
          "description": "Y-m-d."
        },
        {
          "name": "end",
          "required": true,
          "description": "Y-m-d, must be on or after start."
        },
        {
          "name": "symbols",
          "required": true,
          "description": "Comma-separated symbol codes."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "ohlc",
      "method": "GET",
      "path": "/ohlc",
      "description": "Open/high/low/close candles per symbol, bucketed weekly, monthly, or quarterly.",
      "params": [
        {
          "name": "symbols",
          "required": true,
          "description": "Comma-separated symbol codes."
        },
        {
          "name": "period",
          "required": false,
          "description": "weekly, monthly, or quarterly. Default: monthly."
        },
        {
          "name": "start",
          "required": false,
          "description": "Y-m-d. Defaults to a lookback window based on the account plan (365 days if unset/unauthenticated)."
        },
        {
          "name": "end",
          "required": false,
          "description": "Y-m-d, must be on or after start. Defaults to today."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "electricity_latest",
      "method": "GET",
      "path": "/electricity/latest",
      "description": "Latest day-ahead electricity price(s), optionally filtered by country. Covers day-ahead auction symbols across European and global markets (e.g. OMIE_ES_DA, EPEX_DE_DA, AEMO_NSW1_SPOT).",
      "params": [
        {
          "name": "country",
          "required": false,
          "description": "ISO 3166-1 alpha-2 country code, e.g. ES, DE."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "electricity_hourly",
      "method": "GET",
      "path": "/electricity/hourly",
      "description": "Intraday electricity price curve (hourly, 15-minute, or 5-minute, depending on the source) for one symbol on one date. Only symbols with intraday storage enabled are supported.",
      "params": [
        {
          "name": "symbol",
          "required": true,
          "description": "e.g. OMIE_ES_DA. Use GET /symbols to check which symbols support intraday data."
        },
        {
          "name": "date",
          "required": true,
          "description": "Y-m-d."
        }
      ],
      "auth_required": true
    },
    {
      "name": "electricity_pvpc",
      "method": "GET",
      "path": "/electricity/pvpc",
      "description": "Hourly Spanish PVPC (Precio Voluntario para el Pequeño Consumidor) retail reference price for one date. Fixed to symbol PVPC_ES_2TD.",
      "params": [
        {
          "name": "date",
          "required": true,
          "description": "Y-m-d."
        }
      ],
      "auth_required": true
    },
    {
      "name": "gas_latest",
      "method": "GET",
      "path": "/gas/latest",
      "description": "Latest TTF (EU) and Henry Hub (US) natural gas benchmark prices in one call. NBP (UK), JKM (Asia LNG), and AECO (Canada) are not currently sourced.",
      "params": [
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "emissions_latest",
      "method": "GET",
      "path": "/emissions/latest",
      "description": "Latest EU ETS carbon allowance price (EUA_CO2). UK ETS is not currently sourced.",
      "params": [
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "coal_latest",
      "method": "GET",
      "path": "/coal/latest",
      "description": "Latest Rotterdam (API2) and Newcastle thermal coal benchmark prices. COAL_ROTTERDAM may be temporarily absent if the upstream feed is unavailable.",
      "params": [
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to."
        }
      ],
      "auth_required": true
    },
    {
      "name": "carbon_intensity",
      "method": "GET",
      "path": "/carbon-intensity",
      "description": "Grid carbon intensity in gCO2eq/kWh, optionally filtered by country. Country-level series depend on the Electricity Maps provider; an EU average is sourced from Ember.",
      "params": [
        {
          "name": "country",
          "required": false,
          "description": "ISO 3166-1 alpha-2 country code, e.g. DE."
        },
        {
          "name": "base",
          "required": false,
          "description": "3-letter currency code to filter results to (rarely relevant for this endpoint since the unit is gCO2eq/kWh, not a price)."
        }
      ],
      "auth_required": true
    },
    {
      "name": "forecast",
      "method": "GET",
      "path": "/forecast",
      "description": "Next published day-ahead price for a symbol. Day-ahead auctions clear tomorrow's price today, so this is a deterministic lookup of the next already-published value, not a statistical model. Only supported for day-ahead-auction-sourced electricity symbols (omie, entsoe, energy_charts, esios, gridstatus providers) — not EUA_CO2 or other monthly/non-auction symbols.",
      "params": [
        {
          "name": "symbol",
          "required": true,
          "description": "e.g. OMIE_ES_DA."
        }
      ],
      "auth_required": true
    },
    {
      "name": "cost_estimate",
      "method": "POST",
      "path": "/cost-estimate",
      "description": "Estimated monthly electricity cost from a kWh usage figure. MVP scope: most recent daily-average wholesale price x kWh/month. Does NOT account for retail markups, taxes, network charges, or an intraday usage profile — see methodology_note in the response.",
      "params": [
        {
          "name": "symbol",
          "required": false,
          "description": "An electricity symbol, e.g. OMIE_ES_DA. Required if country is omitted."
        },
        {
          "name": "country",
          "required": false,
          "description": "ISO 3166-1 alpha-2 country code, e.g. ES. Required if symbol is omitted; if multiple electricity symbols match the country, pass symbol explicitly instead."
        },
        {
          "name": "kwh_per_month",
          "required": true,
          "description": "Numeric, e.g. 500."
        }
      ],
      "auth_required": true
    },
    {
      "name": "status",
      "method": "GET",
      "path": "/status",
      "description": "Last fetch status (success/failure, duration, error count/message) for each upstream data provider. Useful for checking whether a given source is currently up before relying on its data.",
      "params": [],
      "auth_required": true
    }
  ]
}