Register your application as a third-party (TP) with the utility's Green Button Connect My Data program to receive a client_id and client_secret; each utility runs its own authorization server.
Redirect the customer to the utility's authorization endpoint with response_type=code, client_id, redirect_uri, and scope (typically covering UsagePoint and related ESPI resources).
Exchange the returned authorization code for an access token and refresh token at the utility's token endpoint using a POST with grant_type=authorization_code.
Retrieve the list of usage points via GET /espi/1_1/resource/Subscription/<SUBSCRIPTION_ID>/UsagePoint using the access token as a Bearer token in the Authorization header.
Download interval block data via GET on the ElectricPowerUsageSummary or IntervalBlock resource paths; parse the Atom/XML feed, extracting IntervalReading values, their start timestamps (epoch seconds), and duration.
Known gotchas
ESPI timestamps are Unix epoch integers in UTC; many utilities also embed a local offset in the feed but it is not standardized — always convert using UTC and apply the utility's timezone separately to avoid DST errors.
Each utility implements Green Button Connect independently, meaning endpoint paths, scope strings, and XML namespace usage vary significantly despite the shared standard; test against each utility's sandbox before production.
Refresh tokens issued by utility authorization servers often have long but finite lifetimes (sometimes 1 year) and may not auto-renew; implement expiry tracking and prompt re-authorization well before tokens lapse to avoid data gaps.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp