# EIA MCP Server for Microsoft Copilot Studio

A Python FastMCP server that wraps the U.S. Energy Information Administration Open Data API v2 and exposes agent-friendly tools over Streamable HTTP.

## Tools

- `discover_eia_route`: discover routes, frequencies, columns, and facets.
- `get_eia_data`: query any EIA v2 dataset using a controlled relative route.
- `get_electricity_retail_sales`: convenience tool for annual state-level retail electricity data.

## 1. Configure

Request a free EIA API key from https://www.eia.gov/opendata/register.php, then:

```bash
cp .env.example .env
```

Set `EIA_API_KEY` in `.env`. Never commit that file.

## 2. Run locally

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
set -a && source .env && set +a
python server.py
```

The MCP endpoint is:

```text
http://localhost:8000/mcp
```

Test it with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
```

## 3. Run with Docker

```bash
docker compose up --build
```

## 4. Deploy for Copilot Studio

Deploy the container to a host that provides a publicly reachable **HTTPS** endpoint, such as Azure Container Apps. Configure `EIA_API_KEY` as a secret, map it to an environment variable, and expose port 8000. The URL supplied to Copilot Studio should end in `/mcp`.

Illustrative Azure Container Apps flow:

```bash
az group create --name rg-eia-mcp --location eastus
az acr create --resource-group rg-eia-mcp --name <uniqueRegistry> --sku Basic
az acr build --registry <uniqueRegistry> --image eia-mcp:1.0 .

az containerapp up \
  --name eia-mcp \
  --resource-group rg-eia-mcp \
  --location eastus \
  --image <uniqueRegistry>.azurecr.io/eia-mcp:1.0 \
  --target-port 8000 \
  --ingress external

az containerapp secret set \
  --name eia-mcp \
  --resource-group rg-eia-mcp \
  --secrets eia-api-key='<YOUR_EIA_KEY>'

az containerapp update \
  --name eia-mcp \
  --resource-group rg-eia-mcp \
  --set-env-vars EIA_API_KEY=secretref:eia-api-key
```

For enterprise use, protect the endpoint with an API key gateway or OAuth 2.0, apply an ingress allowlist where possible, enable application logging, and rotate secrets.

## 5. Connect from Copilot Studio

1. Open the agent and enable **generative orchestration**.
2. Go to **Tools**, choose **Add a tool**, then choose the MCP option/onboarding wizard.
3. Enter `https://<your-host>/mcp`.
4. Configure the authentication method used by your deployment.
5. Add the discovered MCP tools/resources to the agent and publish it.

Suggested agent instruction:

```text
For U.S. energy statistics, use the EIA Energy Data tools. If you do not know a dataset's exact route, frequency, data columns, or facets, call discover_eia_route first. Cite the returned EIA metadata and state the period and units in the answer.
```

## Example agent requests

- "Show annual residential electricity prices in Texas and California from 2020 through 2025."
- "Discover the available petroleum routes in EIA."
- "Query monthly natural-gas data after first discovering the required route and facets."

## Design notes

- The EIA key stays server-side and is never exposed as a tool argument.
- Routes are restricted to relative EIA paths to prevent arbitrary URL access.
- Returned EIA values are preserved because API v2 may represent data points as JSON strings.
- `MAX_ROWS` limits large agent-triggered responses; use `offset` for pagination.
- The server itself does not implement inbound authentication. Add API-key or OAuth protection before production use.