EG4 Entra MCP Lab

A security-focused Model Context Protocol lab for an EG4 inverter. It replaces copied API keys at the MCP boundary with Microsoft Entra authentication and demonstrates three distinct authorization patterns:

1. Direct delegated access from a signed-in MCP client to Gateway API A.

2. True OAuth On-Behalf-Of (OBO) from Gateway A to Energy API B.

3. Application-only read access for a bounded automation client.

The final Energy API to EG4 Monitor hop uses a server-held EG4 portal credential because EG4 does not publish user-delegated OAuth. That hop is deliberately documented as service-credential access, not OBO.

Safety status

• EG4 mode defaults to deterministic mock data.

• Real cloud mode requires an explicit inverter serial allowlist.

• All writes default to disabled: ENERGY_CONTROL_ENABLED=false.

• Quick charge uses a short-lived plan/commit operation with state-drift detection.

• No generic register-write, arbitrary HTTP, or shell tool is exposed.

• EG4 and Entra credentials must never be put in Git, prompts, MCP arguments, logs, or browser storage.

Related MCP server: EG4 MCP Server

Architecture

VS Code/public client -- delegated token (aud=A) --> MCP Gateway A :8930
                                                     |
                                                     | Entra OBO
                                                     v
                                           Energy API B :8931
                                                     |
                                                     | EG4 portal session
                                                     v
                                           EG4 Monitor private API

Only Gateway A has a host port. API B is reachable only on the Compose network and still validates its own Entra audience and permissions.

Entra applications

Provisioning creates four single-tenant applications:

See docs/architecture.md and docs/entra-setup.md.

For the verified security properties, live validation evidence, failure modes, and operational lessons, see docs/security-learnings.md.

MCP tools

• whoami: inspect sanitized Entra authorization claims

• list_inverters: read allow-listed plants/inverters

• get_current_state: power flow, SOC, battery, online and quick-charge state

• plan_quick_charge: no mutation

• plan_stop_quick_charge: no mutation

• commit_operation: mutation only when every server-side gate passes

Local mock development

Copy-Item .env.example .env
# In .env only for isolated local testing:
# GATEWAY_AUTH_DISABLED=true
# ENERGY_AUTH_DISABLED=true
# ENERGY_EG4_MODE=mock
# Create an empty ignored secrets/mock_gateway.pem only for mock Compose startup.
uv sync --extra dev
uv run pytest

A local test MCP bearer is intentionally fixed as local-test-token; it is accepted only with mock auth explicitly enabled.

Container deployment

1. Copy .env.example to a server-only .env and fill in only the documented identifiers and policy values.

2. Run scripts/new_gateway_certificate.ps1, upload only gateway.crt.pem with the provisioning script, and mount only the ignored private gateway.pem into Gateway A. See docs/entra-setup.md.

3. Install EG4 credentials interactively with scripts/install_eg4_credentials.sh; the secret directory is an optional first argument.

4. Generate ignored certs/eg4-gateway.crt and certs/eg4-gateway.key files with SANs for the published hostname. Trust only the public certificate on the client.

5. Keep ENERGY_EG4_MODE=mock and ENERGY_CONTROL_ENABLED=false for the first deployment, then run docker compose up -d --build.

6. Verify https://127.0.0.1:8930/healthz and the RFC 9728 metadata route. Set GATEWAY_BIND_ADDRESS, GATEWAY_PUBLIC_BASE_URL, and GATEWAY_ALLOWED_HOSTS explicitly before publishing to another trusted host.

MCP clients

Copy .vscode/mcp.example.json to .vscode/mcp.json for an OAuth-capable client and substitute the generated public client ID. Do not put a client secret or bearer token in that file.

For clients that support stdio but not interactive remote MCP OAuth, this repo provides a local bridge. eg4-client-login performs Entra device-code or browser sign-in and stores the serialized MSAL cache in the OS credential store. eg4-client-bridge silently refreshes the session and proxies the authenticated remote MCP over stdio. Both commands take --tenant-id, --client-id, --scope api://GATEWAY-CLIENT-ID/Mcp.Read, and optionally --mcp-url.

EG4 caveat

EG4 Monitor has no public supported developer API found during research. This project calls a community reverse-engineered portal API through pylxpweb, pinned to a tested version. Read and control behavior can vary by role, model, and firmware.

License

MIT. This project is unaffiliated with EG4 Electronics or Microsoft.