[Docs](/docs) / Energy

# Energy

Discover supported US Energy Information Administration datasets and fetch energy observations with their original units and source links.

## Call it

Use an agent API key, including a tenant sub-key. Management credentials cannot call tools. Available tools appear on your combined MCP endpoint when switched on.

```
https://mcp.deep.navy/mcp
```

Check [Tools in the dashboard](/dashboard/tools) for current availability. Your MCP client reads the current input and output schemas from the server. These are on-demand provider lookups; source freshness and coverage differ by dataset. For API-key provisioning, see the [platform API guide](/docs/platform); for failures and retries, see [limits and errors](/docs/limits).

## Coverage and interpretation

Search the supported dataset catalog before fetching observations. Dataset frequency, dimensions and units differ; retain those fields when comparing values.

The initial catalog covers electricity retail sales, electric-power operations, weekly petroleum stocks and weekly natural-gas storage.

Energy statistics follow their source publication schedule and can be revised. They are not a live commodity-price feed.

Dataset discovery and observation fetching are available in beta through the platform’s EIA connection. Customers do not need a separate EIA API key; availability is shown in the dashboard tool catalog.

## energy_search

Search the supported EIA dataset catalog for dataset IDs, columns, frequencies and filters.

- query is optional (up to 200 characters); omit it to list the supported dataset catalog. Discovery has no limit or pageToken and does not search observation values.
- Read results\[].id, columns, frequencies, defaultColumn, defaultFrequency and facets (including exampleValues) before fetching. available reports whether the platform’s provider connection is configured; current tool enablement also appears in the dashboard. Your own EIA key is not needed.

## Example request: `energy_search`

Arguments for an MCP tools/call request. The values returned depend on the source’s current data.

```
{
  "name": "energy_search",
  "arguments": {
    "query": "electricity"
  }
}
```

Direct HTTP API: POST the argument object to `deepnavy.energy.v1.EnergyService/Search`. The response is the protobuf JSON body, without an MCP envelope. Set `DEEPNAVY_KEY` in your environment before running:

```
curl --fail-with-body --request POST 'https://api.deep.navy/deepnavy.energy.v1.EnergyService/Search' \
  --header "Authorization: Bearer $DEEPNAVY_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{"query":"electricity"}'
```

## energy_fetch

Fetch observations from a supported EIA dataset. Use the columns, frequency and facets returned by energy_search.

- dataset is required and must match an ID from energy_search. Select one supported column and frequency, or omit them to use that dataset’s defaults. The adapter supports the reviewed catalog, not arbitrary EIA API paths.
- start and end use YYYY for annual, YYYY-Q1 through YYYY-Q4 for quarterly, YYYY-MM for monthly, or YYYY-MM-DD for weekly data. Match the chosen frequency and put start before or equal to end. Omit date bounds to request the latest available periods first.
- filters accepts up to four distinct facets, each with 1–20 values. Use facet IDs and values from discovery; supply a facet once with multiple values. limit defaults to 50 and supports up to 200 observations.
- Copy nextPageToken into pageToken to continue with the same dataset, column, frequency, dates and filters. Read period, unit and dimensions on every observation. value is decimal text preserved from EIA; missingReason explains absent or suppressed values, which must not become zero. retrievedAt is retrieval time, not the observation’s publication date. Check warnings; provider revisions can change later pages.

## Example request: `energy_fetch`

Arguments for an MCP tools/call request. The values returned depend on the source’s current data.

```
{
  "name": "energy_fetch",
  "arguments": {
    "dataset": "electricity/retail-sales",
    "column": "price",
    "frequency": "monthly",
    "filters": [
      {
        "facet": "stateid",
        "values": [
          "CA"
        ]
      },
      {
        "facet": "sectorid",
        "values": [
          "RES"
        ]
      }
    ],
    "limit": 12
  }
}
```

For the next MCP page, resend the example arguments with `pageToken` set to the exact `nextPageToken` from your response. Stop when no token is returned. Treat tokens as opaque; start a new request if you change the filters.

Direct HTTP API: POST the argument object to `deepnavy.energy.v1.EnergyService/Fetch`. The response is the protobuf JSON body, without an MCP envelope. Set `DEEPNAVY_KEY` in your environment before running:

```
curl --fail-with-body --request POST 'https://api.deep.navy/deepnavy.energy.v1.EnergyService/Fetch' \
  --header "Authorization: Bearer $DEEPNAVY_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{"dataset":"electricity/retail-sales","column":"price","frequency":"monthly","filters":[{"facet":"stateid","values":["CA"]},{"facet":"sectorid","values":["RES"]}],"limit":12}'
```

## Sources, documentation and reuse

Source: U.S. Energy Information Administration (EIA). EIA permits reuse and distribution of its public data, with exceptions for separately identified third-party content. Keep the returned attribution and source links.

- [EIA homepage](https://www.eia.gov/)
- [Open Data and API browser](https://www.eia.gov/opendata/)
- [API technical documentation](https://www.eia.gov/opendata/documentation.php)
- [Copyright and reuse policy](https://www.eia.gov/about/copyrights_reuse.php)

---

This is the Markdown copy of https://deep.navy/docs/energy.