# Amperical Energy Market MCP

Agent documentation | Updated 23 October 2026

## Start here

- ISO: Independent System Operator; DA/RT: day-ahead/real-time
- MCP: Model Context Protocol over Streamable HTTP
- Spread queries cover listed ERCOT, CAISO and NYISO locations
- `get_heat_price` trial covers 34 hubs across seven ISOs
  - ERCOT, CAISO, PJM and MISO
  - NYISO, SPP and ISO-NE
- Endpoint: `https://ai.amperical.ai/energy-data/mcp`
- Trial needs no key; [live coverage][coverage] lists spread sources and windows

## Prompt for your agent

```text
Read https://amperical.ai/data/docs.md and use the Amperical Energy Market MCP.
Check live coverage first. Compare day-ahead TB4 spreads at listed locations
in ERCOT, CAISO and NYISO for the latest seven-day window in live coverage.
Use get_heat_price for the latest seven days of hub weather, estimated ISO net
load and day-ahead/real-time mean-price changes across all seven ISOs.
If useful, inspect public ERCOT and CAISO battery energy storage system (BESS)
leaderboard reports using their published windows and methods. Explain dates,
gaps and limits. Spreads are not battery revenue. If needed, show me how to
add the MCP URL in this client.
Do not submit an access request without my instruction.
```

## Connect from your client

- Add the server URL to your client's remote MCP or custom-tool settings
- Select Streamable HTTP
- Leave authentication off for the public trial
- Client names, connection screens and plan support vary
- Agents with HTTP or code tools can use the example below
- Browsing-only agents can read the docs and catalog without query tools
- No specific agent application is required by this service

### Licensed access

- Introductory price: $49 USD per organization-month
- Billing: manual invoices with customer-approved renewals
- Both tiers cover all listed spread locations
- Spread history: from January 2025; exact dates are in live coverage
- Spread outputs: daily and monthly TB2, TB4, TB6 and TB8
- EIA and Overture context: both tiers, as listed in live coverage

### Configure your key

- Configure this header in your client's private connection settings

```http
Authorization: Bearer YOUR_ORG_ACCESS_KEY
```

- Replace the placeholder with your organization's key
- Update the existing connection when moving from trial to full access
- Keep the key out of prompts, shared files and public logs
- Paid access requires a client that can send a custom Bearer header
- Clients limited to OAuth cannot use these keys directly

## Query workflow

1. Call `list_coverage` for sources, date windows and query limits
2. Call `find_locations` within one available ISO
3. Call `get_spreads` separately for each chosen location
4. Call `get_heat_price` for weather, load and DA/RT mean-price changes
5. Call `get_context` for EIA or Overture when relevant to the question
6. Call `get_bess_leaderboard` for public ERCOT or CAISO report values
7. Report methods, units, missing dates and source credits

### list_coverage

- Arguments: `{}`
- Returns source metadata, location counts, query limits and report windows
- Reports the current trial window dates
- Separate `leaderboards` metadata lists availability, dates and methods
- Date bounds do not guarantee every location has every date

### find_locations

- Required: `iso`, one of `ercot`, `caiso` or `nyiso`
- Optional: `query`, a location-name or code fragment
- Search the live catalog for listed settlement locations
- Both tiers return at most 50 locations per search

```json
{"iso": "ercot", "query": "ESR"}
```

### get_spreads

- Required: `iso` and an exact `location` from the catalog or search
- Optional: `start_date`, `end_date` and `period`
- Dates use `YYYY-MM-DD`
- Period: `day` or `month`

```json
{"iso": "ercot", "location": "EXACT_LOCATION_FROM_CATALOG"}
```

### get_heat_price

- Optional `hub`; empty returns all 34 hubs
- `days`: integer 1–7 in trial or 1–92 with full access; other values are rejected
- Trial returns the latest days; setting `end_date` is rejected
- Full `end_date` uses `YYYY-MM-DD`; default is the latest available date
- One hub can return up to 92 days
- All-hub cap: 34 hubs × 7 days = 238 hub-days per query
- Full access returns `next_end_date` for paging back

```json
{"hub": "", "days": 7}
```

### get_heat_price fields

- Daily maximum, minimum and mean temperature are in °F
- Net load is estimated in MW and shared by hubs in the same ISO
- Mean DA/RT hub prices and both DA/RT TB4 fields are in USD/MWh
- Also returned: degree days, temperature baselines and TB4 baselines/changes

### Weekly change fields

- For date D, pair each daily value with that date's value from D−7
- Temperature change is the mean of three daily differences in °F
- Net-load and DA/RT changes average three daily log ratios, converted to %
- A weekly change requires all three daily pairs to have data
- Each DA or RT price change needs all six daily means at least $5/MWh
- Otherwise the corresponding price-change field is `null`
- Price changes use log ratios after flooring prices at $1/MWh
- Other nulls mark missing or suppressed data

### Spread query limits

- Trial: any listed location, latest seven-day window in live coverage
- Omit dates for a trial query to use the current seven-day window
- Full access: one spread location and at most 92 days per query
- Monthly date ranges must align with whole calendar months
- Monthly results require a complete daily record for every requested day
- A month with missing days is unavailable, rather than partly averaged
- Unsupported requests are rejected

### get_bess_leaderboard

- Required `iso`: `ercot` or `caiso`
- Optional `query`: empty string by default
- Optional `limit`: 1 to 50, with 50 by default
- Optional `offset`: 0 by default
- Returns ranked public display values, free in both tiers

```json
{"iso": "ercot", "query": "", "limit": 50, "offset": 0}
```

### Leaderboard interpretation

- ERCOT monthly equivalent: estimated settlement revenue per kW-month
- ERCOT daily yield: USD per MW of active capacity
- CAISO: federal merchant-revenue filings, per kW-month over four quarters
- CAISO excludes resource adequacy capacity payments
- Values retain the source's displayed rounding
- Some public values are ranges instead of exact figures
- Different periods and methods prevent direct yield comparisons
- Full report context: [ERCOT][ercot_board] and [CAISO][caiso_board]

### Leaderboard response

- `report` includes ISO, source URL, dates and the metric or method notice
- `columns` label the public fields
- Rows include integer `rank`, string `asset` and `fields` with display strings
- `total_matches` and `next_offset` support pagination

### get_context

- Required: `source`, either `eia` or `overture`
- Optional: `region`, default `US`
- EIA: operating and planned fleet counts and nameplate MW
- EIA regions: `US`, `TX`, `CA` and `NY`
- Overture: US power-line and cable record counts and release metadata
- Overture context includes attribution and the free database link

```json
{"source": "eia", "region": "TX"}
```

### request_full_access

- Use only after the user asks to request paid access
- Required: `email`, `organization`, `use_case` and `request_id`
- Generate a UUID for `request_id`
- Reuse that UUID and identical details for retries
- Returns a durable confirmation reference
- Paid keys follow the agreed invoice, separate from the request
- Amperical follows up about the invoice and organization key
- Access questions can also go to [indresh@amperical.ai][contact]

## Reading the results

- TBx: x is 2, 4, 6 or 8 hours
- Formula: mean of x highest hourly prices minus mean of x lowest prices
- Unit: USD/MWh
- Days use the ISO's local operating day, including DST
- Calculations require complete 23-, 24- or 25-hour days
- Monthly value: mean daily spreads across a complete calendar month
- Daily results list missing dates

### Interpretation limits

- `get_spreads` uses day-ahead prices; it has no real-time spread series
- Spreads are screening measures, not realized battery revenue
- The measure assumes perfect foresight and lossless charging
- Fees, dispatch constraints, degradation and ancillary revenue are excluded
- Arbitrary intraday queries are unavailable

## HTTP example for coding agents

- Read-only Python example using the standard library
- Run only where the agent has permission to make HTTPS requests
- The example reads coverage without an API key
- [MCP transport specification][mcp] defines the request protocol

```python
import json
import time
from urllib.request import Request, urlopen

endpoint = "https://ai.amperical.ai/energy-data/mcp"
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
}
request_number = 0

def rpc(method, params=None, notification=False):
    global request_number
    time.sleep(1)
    message = {"jsonrpc": "2.0", "method": method}
    if params is not None:
        message["params"] = params
    if not notification:
        request_number += 1
        message["id"] = request_number
    request = Request(endpoint, json.dumps(message).encode(), headers)
    with urlopen(request, timeout=30) as response:
        body = response.read()
    return json.loads(body) if body else None

initialized = rpc("initialize", {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "energy-data-reader", "version": "1.0"},
})
headers["MCP-Protocol-Version"] = initialized["result"]["protocolVersion"]
rpc("notifications/initialized", notification=True)
coverage = rpc("tools/call", {"name": "list_coverage", "arguments": {}})
print(json.dumps(coverage, indent=2))
```

### Response handling

- Endpoint: stateless, with JSON responses to POST requests
- Use `tools/list` for current tool schemas
- Use `tools/call` with a tool's `name` and `arguments` to query it
- HTTP 429: pause before retrying
- Per-IP capacity is shared across clients
- HTTP 401: check the paid key's expiry or revocation
- Invalid paid keys cannot fall back to trial
- Tool errors appear as `isError`, separate from empty data

## Sources and licensing

- The service returns calculations without redistributing raw ISO price rows
- CAISO/NYISO withdrawal trigger: the ISO's objection under its data terms
- Source or output withdrawal applies to both access tiers
- Credit EIA to the U.S. Energy Information Administration
- Each weather result credits [Open-Meteo][open_meteo] under [CC BY 4.0][cc_by]
- Overture attribution: © OpenStreetMap contributors and Overture Maps Foundation
- The [Overture database][odbl_data] is free under [ODbL-1.0][odbl]
- Overture reuse under ODbL needs no Amperical analytics license

### Analytics license

- Use computed analytics inside your licensed organization
- [Service terms][terms] cover licensing, source rights and refunds
- Lost paid coverage permits a prorated unused-period refund

[contact]: mailto:indresh@amperical.ai?subject=Energy%20data%20access
[coverage]: https://ai.amperical.ai/energy-data/coverage
[ercot_board]: https://amperical.ai/ercot-leaderboard/
[caiso_board]: https://amperical.ai/caiso-leaderboard/
[mcp]: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
[open_meteo]: https://open-meteo.com/
[cc_by]: https://creativecommons.org/licenses/by/4.0/
[odbl]: https://opendatacommons.org/licenses/odbl/1-0/
[odbl_data]: https://ai.amperical.ai/energy-data/odbl/transmission_lines.parquet
[terms]: https://amperical.ai/data/terms.html