Energy tools (@dmtr/mcp)

Overview

@dmtr/mcp is the MCP server that exposes the energy vertical to agents. It runs as a stdio process — the MCP client (Claude Desktop, Cursor, custom agent) spawns it and communicates over stdin/stdout. The server forwards reads to the DMTR REST API at DMTR_API_URL (default http://localhost:3100/v1) and reads regulatory-corpus data directly from @dmtr/energy/regulatory.

For the auth posture (stdio is local-and-trusted; HTTP transport is intentionally not exposed in this version) see Auth.

The ten energy tools

evaluate_demand_compliance is named honestly: it returns a regulatory-compliance Verdict, not an economic price-based match. Pricing primitives (collateral haircut, mark methodology, forward curve) ship in a follow-on sprint with cited reference fixtures rather than invented numbers.

Resources

Resources are read-only static data — no API round-trip. Discoverable via the MCP resources/list request before any tool is called.

Tool reference

query_slot_inventory

List slots with optional client-side filters. Returns a slim summary view per slot — for full detail use inspect_slot.

// input
{
  "country": "AR",                 // optional ISO-3166 alpha-2
  "site_class": "gas_associated",  // optional enum value
  "status": "under_development",   // optional SlotLifecycleStatus
  "min_capacity_mw": 100,          // optional bounds
  "max_capacity_mw": 1000
}

// output (text/JSON)
{
  "count": 1,
  "slots": [{
    "slot_id": "slot-pampa-jv-phase1",
    "site_name": "Pampa JV — Rincón de Aranda associated-gas Phase 1",
    "site_class": "gas_associated",
    "capacity_mw": 200,
    "status": "under_development",
    "country": "AR",
    "subdivision": "Neuquén",
    "tax_stability_regime": "AR_RIGI",
    "regulatory_corpus_id": "AR@2026-05-06.1",
    "vpu_id": "vpu-pampa-rda-ampliacion-001",
    "current_gate": "permits"
  }]
}

inspect_slot

Full slot detail plus the open counsel-review assumptions on the pinned regulatory corpus — so an agent can see in one call which RED items hang over the slot.

// input
{ "slot_id": "slot-pampa-jv-phase1" }

query_stage_gate_status

Stage-gate state pulled to top-level. Includes the canonical 9-step sequence (LAND → ENERGY → PERMITS → SUBSTATION → TURBINES → FINANCE → BUILD → ENERGIZE → TENANT) and the prerequisite map so an agent can plan the next viable transition without round-trips.

// input
{ "slot_id": "slot-pampa-jv-phase1" }

// output
{
  "slot_id": "slot-pampa-jv-phase1",
  "current_gate": "permits",
  "current_status": "in_progress",
  "overall_dev_pct": 0.15,
  "gate_history": [...],
  "canonical_sequence": ["land", "energy", "permits", "substation", "turbines", "finance", "build", "energize", "tenant"],
  "prerequisites": { ... }
}

query_jurisdictions

Index of available regulatory corpus snapshots. Distinguishes active from stub so an agent knows which jurisdictions are production-ready.

inspect_regulatory_corpus

Full snapshot — authorities with statutory citations, tax-stability regimes (RIGI sector floors etc.), indigenous-consultation regime, resource-adequacy programs, open assumptions.

// input
{
  "country": "AR",
  "corpus_version": "2026-05-06.1"  // optional; latest if omitted
}

list_open_assumptions

Focused view of the RED items in a corpus snapshot. Each carries id, question, current_position (pending_counsel_opinion / counsel_confirmed / counsel_disconfirmed), conservative_default, implication_if_disconfirmed, and counsel_routed_to.

// input
{ "corpus_id": "AR@2026-05-06.1" }

For Argentina at this corpus version, returns the five questions documented at Counsel review items.

submit_demand

Persist a structured DemandSpec. Does NOT match — use evaluate_demand_compliance separately.

// input
{
  "demand_spec": {
    "demand_id": "demand-hyperscaler-2027-q2-latam",
    "tenant_participant_id": "hyperscaler-tenant-001",
    "status": "open",
    "capacity_mw_min": 800,
    "duration_months": 60,
    "earliest_energization": "2027-06-01",
    "latency_class": "agnostic",
    "workload_class": "batch_inference",
    "power_quality": "interruptible",
    "geography_filter": { "allowed_countries": ["AR", "CL", "PY", "UY", "BR"] },
    "compliance_requirements": ["bis_export_clean", "ofac_clean", "rigi_eligible"],
    "cfe_matching_request": "hourly_grid"
  }
}

Validation against the authoritative DemandSpec schema happens at the API; field-level errors are returned with status 400.

evaluate_demand_compliance

Run the energy rights-engine over a DemandSpec against current slot inventory. Returns a ranked array of compliance Verdicts. Not an economic price-based match.

// input
{
  "demand_id": "demand-hyperscaler-2027-q2-latam",
  "tenant_ofac_screened_at": "2026-04-30",
  "estimated_project_value_usd": 800000000
}

// output
{
  "demand_id": "demand-hyperscaler-2027-q2-latam",
  "results": [{
    "slot_id": "slot-pampa-jv-phase1",
    "score": 0.86,
    "allowed": true,
    "conditional": true,
    "missing_compliance": [],
    "mw_offered": 200,
    "notes": "permit_stack: Permits in progress (acceptable for development-stage slots): [environmental_impact, air_emissions]."
  }]
}

compute_capacity_payment_preview

Pure-function preview of the monthly capacity payment. Calls @dmtr/energy/settlement directly — no API round-trip, no state change. Lets an agent run what-if analysis ("if availability drops to X% for the month, what is the reduced capacity payment?") without persisting anything.

// input
{
  "contract_capacity_mw": 200,
  "monthly_payment_usd": "5000000",
  "availability_threshold_pct": 0.92,
  "hourly_availability_mw": [195, 195, ... 720 entries],
  "heat_rate_target_btu_per_kwh": 7800,           // optional
  "actual_heat_rate_btu_per_kwh": 8190,           // optional
  "heat_rate_adjustment_per_pct": 1                // optional
}

// output
{
  "availability": { "availability_pct": 0.975, "below_threshold": false, ... },
  "payment": { "reduced_monthly_capacity_payment_usd": 4875000, ... },
  "notes": "Pure preview — no state change, no contract persisted."
}

inspect_chip_sku

ChipSku metadata for BIS export-control evaluation — vendor, ECCN tagging, TPP estimate, interconnect bandwidth, TDP, HBM capacity, current commercial-availability posture.

// input
{ "sku": "NVIDIA_H100" }   // ChipSku enum value

// output
{
  "sku": "NVIDIA_H100",
  "vendor": "NVIDIA",
  "ecn_3a090": true,
  "ecn_4e091_paired": false,
  "tpp_estimate": 1979,
  "interconnect_bw_gb_per_s": 900,
  "tdp_watts": 700,
  "hbm_capacity_gb": 80,
  "commercial_availability": "license_required_to_PRC",
  "notes": "Hopper architecture, 80GB HBM3"
}

Per-SKU regulatory posture reflects corpus snapshot AR@2026-05-06.1 / US@stub. Reconfirm against vendor datasheets at procurement time.

Local development

# Terminal 1: run the API the MCP server proxies to
pnpm --filter @dmtr/api dev   # http://localhost:3100

# Terminal 2: run the MCP server (stdio)
pnpm --filter @dmtr/mcp dev

Wire it into Claude Desktop or Cursor by pointing the client at node ./packages/mcp/bin/dmtr-mcp.mjs with DMTR_API_URL=http://localhost:3100/v1 in the MCP server config.

What is intentionally not shipped

• Pricing tools — collateral haircut, mark methodology, forward-curve. Deferred to a follow-on sprint with cited reference fixtures rather than invented numbers.
• HTTP / SSE transport — only stdio in this version. HTTP requires a Bearer-JWT auth layer matching the existing /v1 REST API; that ships in a focused auth sprint.
• Mutation-heavy tools — only submit_demand mutates today. Adding tools that advance stage gates, decompose slots, sign contracts, or issue dispatch notices is feasible against existing routes but introduces operational risk under stdio's local-trusted model. Defer until HTTP + auth ship.