Skip to main content

Using SENS with AI agents (MCP)

sens-mcp is a Model Context Protocol server and developer starter kit that teaches LLMs (Claude Desktop, Cursor, LangChain, n8n, ...) the vocabulary of the Polish electricity market (OSD vs. sprzedawca, tariff groups G11/G12/G12w/...) and lets them safely query the SENS API without hand-writing a REST integration.

Note: the sens-toolkit repository is currently local and private — the GitHub link below (SofiaFlux/sens-toolkit) assumes an eventual open-source release and is not yet live. Until publication, treat this page as a description of the intended end state.

Why not just raw REST?​

  • Market vocabulary available out of the box — the MCP resource sens://market/cheat-sheet teaches the model the basics (OSD, sprzedawca, tariff groups) in under ~400 tokens, instead of relying on the model to guess Polish market terminology.
  • Self-correcting errors — tools return structured JSON with suggestions (did you mean G12w?) instead of a raw HTTP failure, so an agent in a ReAct loop can repair its own next call.
  • Single source of truth for calculations — all price/volume math happens on the SENS backend; the toolkit never re-derives totals client-side.

Install​

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

or pip​

pip install sens-mcp
export SENS_API_KEY=sens_live_your_key_here
python -m sens_mcp
VariableRequiredDefaultDescription
SENS_API_KEYYes—Your SENS API key. Sent as the X-API-KEY header.
SENS_BASE_URLNohttps://api.getsens.energyOverride for staging/self-hosted deployments.

Claude Desktop configuration​

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sens-energy": {
      "command": "uvx",
      "args": ["sens-mcp"],
      "env": {
        "SENS_API_KEY": "sens_live_your_key_here"
      }
    }
  }
}

Cursor configuration​

Same shape, in .cursor/mcp.json:

{
  "mcpServers": {
    "sens-energy": {
      "command": "uvx",
      "args": ["sens-mcp"],
      "env": {
        "SENS_API_KEY": "sens_live_your_key_here"
      }
    }
  }
}

Tools exposed​

ToolPurpose
resolve_operator(query, region=None)Fuzzy-resolves a city or company name (typo-tolerant) to the exact osd/sprzedawca strings the API expects.
search_tariffs(customer_type, zone_preference=None, operator=None)Discovers valid tariff codes for a customer profile (home / small business / industry).
get_prices(osd, taryfa, ...)Fetches composite electricity prices and rate breakdown; pass annual_kwh for exact volume-weighted totals.
get_tariff_components(tariff_id)Inspects a tariff's URE-approved fixed/variable rate components.

Resource sens://market/cheat-sheet — a Markdown cheat sheet of Polish electricity market vocabulary (OSDs, tariff groups, price component structure).

Repository​

Source code, tests, and examples: github.com/SofiaFlux/sens-toolkit (placeholder — the repo is local-only today; see the note at the top of this page).