Using HESTIA with AI assistants

HESTIA publishes a Model Context Protocol (MCP) server. This allows AI agents and tools to search and read HESTIA's public data directly. It also helps your assistant analyse data, create charts and understand how results were calculated. It provides links to help you cite the data accurately and credit the people who created it.

You can connect through Codex, Claude, Antigravity or another tool that supports remote MCP servers. You do not need a HESTIA account to read public data. The connector is read-only, so it cannot change data on HESTIA.

Connecting

The server URL is https://api.hestia.earth/mcp. If your tool asks, choose Streamable HTTP as the transport and no authentication for public data.

Codex

With the Codex CLI installed, run this command in your terminal:

codex mcp add hestia --url https://api.hestia.earth/mcp

Check that it has been added:

codex mcp list

Start a new Codex session. Enter /mcp in the terminal interface to check that HESTIA is available. The Codex CLI and IDE extension share MCP settings; restart the extension if it is already running. See the OpenAI MCP documentation for more options.

Claude Code

Run this command in your terminal:

claude mcp add --transport http hestia https://api.hestia.earth/mcp

Start Claude Code and enter /mcp to check the connection.

Claude

Open Customize → Connectors → Add → Add custom connector. Enter HESTIA as the name and https://api.hestia.earth/mcp as the URL. Continue and choose No sign in for public data.

In a conversation, use the + menu to enable HESTIA under Connectors. On Team or Enterprise plans, an owner may need to add the connector first. See Claude's connector instructions for details.

Antigravity

In the Antigravity CLI, run:

agy mcp add hestia https://api.hestia.earth/mcp

Alternatively, add this entry to mcpServers in ~/.gemini/config/mcp_config.json, keeping any servers you already have:

{
  "mcpServers": {
    "hestia": {
      "serverUrl": "https://api.hestia.earth/mcp"
    }
  }
}

See the Antigravity MCP documentation for how to open and refresh your MCP settings.

Try it

Once connected, ask your assistant:

Use HESTIA to find the glossary term for wheat grain. Show its id and definition.

For an analysis, try:

Use HESTIA to find the average carbon footprint (GWP100) per kg of wheat grain produced in France. State the data release and units, and link to the data and original sources.

Then ask:

Explain which emissions contribute to this result and chart their contributions. Say if the breakdown does not add up to the reported total.

The assistant can find the national aggregation, retrieve its impact results and inspect the emissions behind an indicator. Charts are created by your assistant using the returned data. If the data needed for your question are unavailable, ask the assistant to explain what is missing.

Data releases and early access

Without an access token, the connector uses the latest public data release. With a token, it uses the latest release your account can access. Ask your assistant to state the release alongside its results, as values can change between releases.

Contributing data, open-source code or funding can give you early access to newer releases. See hestia.earth/releases for available versions and how to get access. The connector includes a short notice when a newer release is available.

For more detail, see Data releases and Priority data access.

Using your access token

Use your HESTIA access token to read the releases available to your account. This is the same token used by the HESTIA API. Keep it private and out of chat messages and shared files.

Codex

Add bearer_token_env_var to the existing HESTIA entry in ~/.codex/config.toml:

[mcp_servers.hestia]
url = "https://api.hestia.earth/mcp"
bearer_token_env_var = "HESTIA_ACCESS_TOKEN"

Set HESTIA_ACCESS_TOKEN in the environment that launches Codex, then restart Codex. Use the token alone as the value; Codex adds the Bearer prefix.

Claude Code

If you already added HESTIA without a token, remove that entry with claude mcp remove hestia. Then add it with your token, replacing <your token> below:

claude mcp add --transport http --header "x-access-token: <your token>" hestia https://api.hestia.earth/mcp

Claude

When adding the connector, choose No sign in and add a request header named x-access-token. Set its value to your HESTIA access token, with no prefix. If you already added the connector, remove it and add it again to change authentication.

For an organisation-wide connector, everyone uses the access granted by that token. Check with your workspace owner before using a personal token for a shared connector.

Antigravity

Add headers to your existing HESTIA entry in ~/.gemini/config/mcp_config.json, replacing <your token> below:

{
  "mcpServers": {
    "hestia": {
      "serverUrl": "https://api.hestia.earth/mcp",
      "headers": {
        "x-access-token": "<your token>"
      }
    }
  }
}

You can also supply the header when adding a new connection with the CLI:

agy mcp add --header "x-access-token: <your token>" hestia https://api.hestia.earth/mcp

Other tools

Send the token in the x-access-token header, or use an Authorization header with the value Bearer <your token>. HESTIA does not accept tokens in the URL. An invalid token returns an error.

Available tools

Your assistant chooses which tools to call based on your question.

Citing the data

Ask your assistant to include links and citations with its answers. Credit both HESTIA and the original data creators. For an aggregation, include the underlying sources that contributed to it.

Check the citations against the linked data pages before publishing or sharing your analysis. See Citation and Data Licence for full guidance.