MCP Server Documentation

{
  "commodity": "CL",
  "name": "WTI Crude Oil",
  "sector": "energy",
  "composite_score": 48,
  "direction": "neutral",
  "confidence": "very_low",
  "components": {
    "eia_inventory": { "score": 50, "weight": 0.30, "reason": "Neutral inventory change" },
    "cot_positioning": { "score": 50, "weight": 0.25, "reason": "Neutral z-score 0.33" },
    "curve_structure": { "score": 65, "weight": 0.20, "reason": "Backwardation -$20.46 spread" },
    "momentum": { "score": 95, "weight": 0.15, "reason": "Strong uptrend +48% 3mo ROC" },
    "seasonal_bias": { "score": 35, "weight": 0.10, "reason": "Seasonal headwind week 16" }
  },
  "fair_value": {
    "model_price": 92.00,
    "market_price": 92.52,
    "premium_discount_pct": 0.2,
    "premium_label": "fair",
    "confidence": "medium",
    "methodology": "Inventory-price regression (PAPR_WORLD production vs front-month price)",
    "narrative": "Market trades near model fair value — no significant mispricing detected."
  },
  "volatility": {
    "realized_vol_30d": 0.83,
    "regime": "extreme",
    "percentile": 77.8,
    "confidence_impact": "Signal confidence very low — extreme volatility environment"
  },
  "currency_context": {
    "usd_price": 92.52,
    "dxy_current": 118.86,
    "dxy_change_1w_pct": -1.80,
    "dxy_change_1m_pct": -4.20,
    "usd_change_1w_pct": 5.10,
    "usd_change_1m_pct": 26.80,
    "dollar_contribution_1w_pct": 1.80,
    "real_move_1w_pct": 3.30,
    "dollar_contribution_1m_pct": 4.20,
    "real_move_1m_pct": 22.60,
    "gold_grams_price": 0.6105,
    "gold_denominated_change_1m_pct": 12.10,
    "dollar_impact_narrative": "CL up 26.8% in USD — this is primarily a real supply/demand move (22.6% real vs 4.2% dollar effect). Fundamentals are driving this, not FX."
  },
  "narrative": "WTI composite 48/100 NEUTRAL — inventory data neutral, specs neutral, curve in backwardation confirms near-term tightness, strong upward momentum (+48% 3mo) but extreme volatility (83% annualized) reduces signal reliability.",
  "report_date": "2026-04-22",
  "generated_at": "2026-04-22T14:45:00Z"
}

{
  "commodity": "GC",
  "name": "Gold",
  "cftc_code": "088691",
  "latest": {
    "report_date": "2026-04-04",
    "mm_long": 214530,
    "mm_short": 78210,
    "mm_net": 136320,
    "mm_net_change": 8450,
    "prod_long": 45200,
    "prod_short": 162800,
    "prod_net": -117600,
    "open_interest": 528400,
    "net_z_score": 1.42,
    "net_pct_rank": 87
  },
  "history": [
    {
      "report_date": "2026-03-28",
      "mm_long": 208100,
      "mm_short": 80230,
      "mm_net": 127870,
      "mm_net_change": -3200,
      "prod_long": 44800,
      "prod_short": 160500,
      "prod_net": -115700,
      "open_interest": 521300,
      "net_z_score": 1.28,
      "net_pct_rank": 82
    }
  ],
  "mean_net": 98400,
  "stddev_net": 26700,
  "range_min": -12400,
  "range_max": 168200
}

{
  "commodity": "NG",
  "name": "Natural Gas",
  "series_id": "NG-STORAGE",
  "latest": {
    "period": "2026-04-04",
    "value": 1842,
    "unit": "Bcf"
  },
  "previous": {
    "period": "2026-03-28",
    "value": 1891,
    "unit": "Bcf"
  },
  "weekly_change": -49,
  "weekly_change_pct": -2.59,
  "vs_average": -186,
  "vs_average_pct": -9.17,
  "range_min": 1640,
  "range_max": 2210,
  "history": [],
  "seasonal_note": "9.2% below 5-year average for this week; largest deficit since November"
}

{
  "commodity": "CL",
  "view": "spread",
  "front_contract": "CLK26.NYM",
  "back_contract": "CLZ26.NYM",
  "days": 45,
  "data": [
    { "trade_date": "2026-03-08", "spread": -8.12, "front_price": 82.40, "back_price": 74.28 },
    { "trade_date": "2026-03-15", "spread": -9.85, "front_price": 85.10, "back_price": 75.25 },
    { "trade_date": "2026-03-22", "spread": -12.40, "front_price": 88.60, "back_price": 76.20 },
    { "trade_date": "2026-04-05", "spread": -15.58, "front_price": 91.20, "back_price": 75.62 },
    { "trade_date": "2026-04-22", "spread": -20.46, "front_price": 92.52, "back_price": 72.06 }
  ]
}

{
  "as_of": "2026-04-07T14:00:00Z",
  "total": 24,
  "by_sector": {
    "energy": [
      { "symbol": "CL", "name": "WTI Crude Oil", "sector": "energy", "composite_score": 68, "direction": "bullish", "confidence": "high", "report_date": "2026-04-07", "week_change": 4 },
      { "symbol": "NG", "name": "Natural Gas", "sector": "energy", "composite_score": 42, "direction": "bearish", "confidence": "medium", "report_date": "2026-04-07", "week_change": -6 }
    ],
    "metals": [
      { "symbol": "GC", "name": "Gold", "sector": "metals", "composite_score": 74, "direction": "bullish", "confidence": "high", "report_date": "2026-04-07", "week_change": 2 }
    ],
    "agriculture": [
      { "symbol": "ZC", "name": "Corn", "sector": "agriculture", "composite_score": 51, "direction": "neutral", "confidence": "low", "report_date": "2026-04-07", "week_change": -1 }
    ],
    "macro": []
  },
  "top_bullish": [
    { "symbol": "GC", "name": "Gold", "sector": "metals", "composite_score": 74, "direction": "bullish", "confidence": "high", "report_date": "2026-04-07", "week_change": 2 }
  ],
  "top_bearish": [
    { "symbol": "NG", "name": "Natural Gas", "sector": "energy", "composite_score": 42, "direction": "bearish", "confidence": "medium", "report_date": "2026-04-07", "week_change": -6 }
  ]
}

{
  "report_date": "2026-04-22",
  "headline": "Oil plunges 3.9% as US-Iran talks resume while gold hits fresh high",
  "overnight_summary": "Energy complex sold off sharply on renewed Iran diplomacy hopes. Crude and refined products led losses while gold extended safe-haven gains. Equity markets stable into Fed decision next week.",
  "key_moves": "• CL -3.88% to $86.67 — ceasefire extension hopes reduce supply fears\n• HO -5.99% to $3.45 — refiner margin compression\n• GC +0.62% to $4,839 — fresh 52-week high\n• NG +0.71% — only energy gainer",
  "todays_calendar": "EIA Weekly Petroleum Status Report at 10:30 AM ET · Treasury 10Y auction",
  "levels_to_watch": "CL within 3% of 52-week high ($92.52) · GC at record ($4,839) · NG testing 52-week low ($1.62)",
  "risk_radar": "Ceasefire expires Wednesday — any breakdown sends crude back toward $100",
  "sources": ["Reuters", "Bloomberg", "EIA"],
  "generated_at": "2026-04-22T11:00:00Z"
}

{
  "report_date": "2026-04-20",
  "recap_type": "weekly",
  "executive_summary": "Commodities posted a mixed week as geopolitical risk dominated flows. Oil and refined products rallied 4-6% on Strait of Hormuz disruption before fading into the Friday ceasefire announcement. Gold hit fresh record highs at $4,839 on safe-haven demand. Agriculture finished mixed with wheat up on tight stocks while corn lagged on favorable planting weather.",
  "energy": "WTI closed the week at $92.52, up 5.1% from prior Friday despite Friday's 3.9% pullback. Backwardation steepened to -$20.46/bbl across the front 12 months, signaling acute near-term tightness...",
  "metals": "Gold (+2.1%) and silver (+1.8%) both extended their uptrends with GC hitting $4,839 — a fresh all-time high. The gold/silver ratio compressed to 88, suggesting silver outperformance may continue...",
  "agriculture": "Wheat posted the strongest weekly gain across ag (+3.2%) as USDA stocks came in below trade estimates. Corn (-0.8%) lagged on favorable planting weather. Soybeans held flat as strong Chinese crush margins offset bearish South American supply...",
  "cross_market": "Energy/metals ratio compressed as oil sold off Friday while gold rallied. The Dollar Index weakened -0.4% supporting commodities broadly. 10Y Treasury yield declined 4bps into the Fed decision...",
  "watch_list": "• Wednesday: US-Iran ceasefire expiration + EIA inventory data\n• April 29: Fed rate decision\n• May 12: USDA WASDE report\n• May 2: Apr NFP (affects DXY and yields)",
  "sources": ["Reuters: Oil rises on Iran supply risk", "Bloomberg: Gold hits record high", "EIA: Crude draw 2.1M", "USDA: Wheat stocks below estimates", "CFTC: Managed money net long gold 18-month high"],
  "generated_at": "2026-04-20T23:00:00Z"
}

{
  "scenario_summary": "Strait of Hormuz reopens fully within 30 days, restoring ~16mb/d of flows",
  "historical_analogues": [
    { "event": "2019 Abqaiq attack aftermath", "date": "Oct 2019", "impact": "CL round-tripped +15% spike, gave back all gains within 6 weeks as Saudi flows restored" },
    { "event": "Libya 2011 supply return", "date": "Q3 2011", "impact": "Brent fell from $125 to $100 as 1.6mb/d returned" }
  ],
  "primary_commodity_impact": {
    "commodity": "CL",
    "current_price": 92.52,
    "bull_case": { "probability": 15, "price_target": 98, "rationale": "Partial reopening with recurring incidents keeps risk premium elevated" },
    "base_case": { "probability": 55, "price_target": 78, "rationale": "Full flow restoration collapses $14 risk premium; backwardation unwinds" },
    "bear_case": { "probability": 30, "price_target": 68, "rationale": "Reopening + OPEC+ spare capacity release + demand worry drives washout" },
    "expected_value": 76.4
  },
  "cross_market_effects": [
    { "commodity": "RB", "direction": "down", "magnitude": "-12-18%", "mechanism": "Crack spread compression as crude falls faster than products initially" },
    { "commodity": "HO", "direction": "down", "magnitude": "-10-15%", "mechanism": "Refiner margin normalization" },
    { "commodity": "GC", "direction": "down", "magnitude": "-2-4%", "mechanism": "Safe-haven unwind" }
  ],
  "positioning_context": "Managed money net long CL is at 68th percentile — moderately crowded but not extreme. An unwind would amplify downside by ~$5-8/bbl beyond fundamental target.",
  "key_risks": [
    "Reopening proves incomplete or reverses — crude re-spikes above $100",
    "OPEC+ cuts production to offset returning barrels, supporting prices",
    "Demand weakness materializes simultaneously, driving larger-than-expected selloff"
  ],
  "time_horizon": "4-8 weeks for full price adjustment after reopening confirmation",
  "sources": [
    "Reuters: Iran-US ceasefire talks resume",
    "EIA: Strait of Hormuz carries ~20mb/d",
    "Historical: 2019 Abqaiq recovery timeline"
  ]
}