AI Tools

AI tools quickstart

Use this data with your AI tools

Several ways in: a tool server your agent can call, pages written for models to read, direct data access for code, and instructions that keep an agent accurate. Pick the one that fits, or combine them.

Get a free key Which should I use?

Tool server (MCP)

The quickest route. Connect once and your agent can call 27 read-only tools itself: you ask in plain language and it fetches current data to answer.

https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp

Claude Code

Run this in a terminal.

claude mcp add --transport http toe-energy "https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp" \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project.

{
    "mcpServers": {
        "toe-energy": {
            "url": "https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
            }
        }
    }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace.

{
    "servers": {
        "toe-energy": {
            "type": "http",
            "url": "https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
            }
        }
    }
}

Any app that takes only a URL

Hosted agent platforms and desktop apps often configure a connector with a URL and nothing else. Put the key in the query string.

https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp?api_key=YOUR_API_KEY

Anything else

Any client that speaks MCP over HTTP will work. It needs the endpoint and one header.

URL:     https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/mcp
Header:  Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the key from your data account. Prefer the header form: a key in a URL can end up in server and proxy logs. Your key is stored in plain text in the client's configuration, so keep that file out of shared repositories.

How it works

Your client connects and reads the list of tools and what each is for.
You ask a question. The model decides which tools answer it and calls them.
Each call returns compact, dated data from our store. Nothing is written or changed.
The model answers from what came back, with the dates and sources attached.

Pages written for models

No key and no set-up. Paste one of these links into a chat, or let an agent with web access fetch them. Useful when you want one facility or one topic in context without connecting anything.

What	Where	Use it for
llms.txt	`https://thinkingonenergy.com/llms.txt`	A map of the site for a model: what is here, how URLs are built, how to read and cite the data.
Markdown pages	`https://thinkingonenergy.com/supply/refinery/motiva-enterprises-llc-port-arthur-tx/index.md`	Add index.md to any refinery, pipeline, terminal, ethanol plant or rack market page for a compact version without the page furniture.
JSON records	`https://thinkingonenergy.com/supply/node/refinery/motiva-enterprises-llc-port-arthur-tx.json`	One facility as data: its details, every connection, and a link to the record at the other end, so a program can walk the network.
Vocabulary	`https://thinkingonenergy.com/supply/vocab/`	What each field and relationship in the records means.
Structured data in pages	Every facility page	The same record is embedded as JSON-LD (schema.org), with identifiers, connections and provenance.

The example links are for Motiva Port Arthur Refinery.

REST API

For code you or a coding assistant write: scripts, notebooks, dashboards. Plain HTTPS returning JSON, with the same key as the tool server.

curl -sS "https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1/series?source=eia" \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoint	Returns
`/series`	Every data series: code, name, source, unit, frequency.
`/series/{code}/history`	Observations for one series, with from and to dates.
`/retail-prices`	Retail gasoline and diesel prices by area.
`/infrastructure`	Refineries, terminals, pipelines and markets, filtered by type or state.
`/graph/entity/{type}/{id}`	One facility and its connections.
`/graph/downstream, /graph/upstream`	What a facility supplies, or what supplies it, several steps out.
`/graph/market/{id}`	A rack market: its terminals, pipelines and source refineries.
`/graph/resilience`	How many independent supply sources a market has.

All under https://thinkingonenergy.com/wp-json/toe-energy-dashboard/v1. That address lists every route and its arguments.

Agent instructions

Tools give an agent reach; instructions keep it accurate. Paste this into your project instructions, system prompt or rules file alongside the tool server. It encodes the mistakes we have seen agents make with energy data.

You have the toe-energy MCP server from Thinking On Energy: U.S. energy prices, retail fuel, inventories, refinery operations, trade flows, and a graph of refineries, pipelines, terminals and rack markets built from published FERC tariffs.

- Every number comes from a data tool call made now. Never state a figure from memory or from an article as if it were current.
- Series codes cannot be guessed. Call list_data_series before any tool that takes a series_code.
- Supply chain tools take an entity_type and entity_id. Call find_infrastructure to turn a name or place into an id first.
- Give the date with every figure. Most series are weekly or monthly; call get_data_status before reading meaning into a flat line.
- Forecast rows (the EIA outlook) carry future dates. Label them as forecasts, never as observations.
- Pipeline rates are published line-haul tariffs in cents per barrel (divide by 42 for cents per gallon). They exclude terminal and rack fees.
- Links between facilities are marked confirmed, sourced or inferred. Say which when it matters.
- Articles and news from the content tools are for context. Cite their link and publication date.
- If a tool reports that a call limit was reached, stop calling and tell the user.

Choosing the right approach

Approach	Best for	Key needed	Set-up
Tool server (MCP)	Asking questions and getting current answers; analysis across prices and the supply chain.	Yes	One command or one config entry
Pages for models	Putting one facility or topic into a chat; agents that browse the web.	No	None: paste a link
REST API	Code: scripts, notebooks, your own applications.	Yes	Write the requests
Agent instructions	Any of the above, to stop an agent guessing codes or quoting stale figures.	No	Paste once

Limits and what each plan includes

	Free	Professional
Calls a day	50	2,000
Calls a minute	5	30
AI agent tools (MCP)	All 27	All 27
REST API	Yes	Yes
CSV downloads	No	Yes, where the source allows
Permitted use	Personal	Business, by agreement
Price	Free	By arrangement

A call is one AI tool call, or one direct data request, made with your key. Connecting a client and listing its tools are not counted. The daily count resets at midnight, site time.

At a limit, the agent is told. A tool call past the limit returns a plain message saying which limit was reached and when it resets, so the agent can stop and tell you. A REST request returns status 429.
Free accounts are for personal use. The full terms are on the data account page.
Results are capped in size. A very broad tool call is trimmed and says so, so one call cannot flood a model's context.

Next steps

Get a free key Supply Explorer Data Explorer