Materix Documentation

MCP Server Documentation

Connect your AI assistant to real-time commodity intelligence. Six tools covering signals, positioning, inventories, futures curves, market overviews, and weekly digests.

#Quick Start

Claude.ai Setup

1Open Claude.ai and go to Settings
2Navigate to Connectors (under Features)
3Click Add custom MCP (or Add connector)
4Enter the server URL:
5Click Save — an OAuth login prompt will appear automatically
6Authorize with your Materix account credentials
7You're connected! Try asking Claude about commodity signals

url

https://mcp.materix.dev/mcp

Note: Free tier accounts get energy sector data only with a 7-day delay. Upgrade at materix.dev/pricing for real-time access to all sectors.

#Available Tools

Materix exposes 6 MCP tools. Free tier has access to get_commodity_signal and get_market_overview (energy only, 7-day delay). Pro and Institutional tiers unlock all tools with real-time data.

get_commodity_signal

Free+

Get a composite trading signal with component scores, directional bias, and AI-generated narrative for any supported commodity.

Parameters

Parameter	Type	Required	Description
commodity	string	required	Symbol like "CL" (crude oil), "GC" (gold), "ZC" (corn). Uppercase, 1–10 chars.
timeframe	"weekly" \| "monthly"	optional	Signal timeframe. Defaults to weekly.
custom_weights	object	optional	Custom signal component weights (institutional tier only). Keys: cot_positioning, inventory_deviation, curve_structure, seasonal_bias, macro_context, momentum.

Example Request

"What's the current signal for crude oil?"

Example Response

json

{
  "commodity": "CL",
  "name": "WTI Crude Oil",
  "sector": "energy",
  "composite_score": 68,
  "direction": "bullish",
  "confidence": "high",
  "components": {
    "cot_positioning": 72,
    "inventory_deviation": 61,
    "curve_structure": 78,
    "seasonal_bias": 55,
    "macro_context": 64,
    "momentum": 70
  },
  "weights": {
    "cot_positioning": 0.30,
    "inventory_deviation": 0.10,
    "curve_structure": 0.25,
    "seasonal_bias": 0.10,
    "macro_context": 0.15,
    "momentum": 0.10
  },
  "narrative": "WTI crude maintains a bullish posture as managed-money longs extend for a third consecutive week. Backwardation across the front 6 months signals tightening physical supply, corroborated by a 2.1M-barrel draw in EIA commercial stocks. Seasonal tailwinds from refinery maintenance season winding down add modest support.",
  "report_date": "2026-04-07",
  "generated_at": "2026-04-07T14:32:00Z",
  "data_delay_days": 0
}

get_cot_positioning

Pro+

Retrieve CFTC Commitments of Traders positioning data with z-scores and percentile rankings.

Parameters

Parameter	Type	Required	Description
commodity	string	required	Commodity symbol (e.g. CL, GC, ZC).
weeks	integer	optional	Weeks of history to return (4–104). Defaults to 52.

Example Request

"Show me COT positioning for gold over the last 12 weeks"

Example Response

json

{
  "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
}

get_inventory_levels

Pro+

Get current inventory/storage levels with weekly changes, seasonal comparisons, and historical data.

Parameters

Parameter	Type	Required	Description
commodity	string	required	Symbol like "CL", "NG", "ZC".
periods	integer	optional	Number of periods to return (4–104). Defaults to 13 (one quarter).
compare_seasonal	boolean	optional	Include seasonal deviation analysis. Defaults to true.

Example Request

"What are current natural gas storage levels?"

Example Response

json

{
  "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"
}

get_futures_curve

Pro+

Retrieve the futures term structure with curve shape analysis, term spread, and estimated roll yield.

Parameters

Parameter	Type	Required	Description
commodity	string	required	Commodity symbol.
months	integer	optional	Number of contract months (2–24). Defaults to 12.

Example Request

"Show me the crude oil futures curve"

Example Response

json

{
  "commodity": "CL",
  "name": "WTI Crude Oil",
  "shape": "backwardation",
  "front_price": 78.42,
  "term_spread": -4.18,
  "roll_yield_est": 5.33,
  "curve": [
    { "month": 1, "label": "May '26", "price": 78.42, "as_of": "2026-04-07" },
    { "month": 2, "label": "Jun '26", "price": 77.85, "as_of": "2026-04-07" },
    { "month": 3, "label": "Jul '26", "price": 77.10, "as_of": "2026-04-07" },
    { "month": 6, "label": "Oct '26", "price": 75.60, "as_of": "2026-04-07" },
    { "month": 12, "label": "Apr '27", "price": 74.24, "as_of": "2026-04-07" }
  ],
  "prior_week": [
    { "month": 1, "label": "May '26", "price": 77.90, "as_of": "2026-03-31" }
  ],
  "as_of": "2026-04-07"
}

get_market_overview

Free+

Get a cross-market summary with composite scores, directional bias, and top bullish/bearish movers across all sectors.

Parameters

Parameter	Type	Required	Description
sector	"energy" \| "metals" \| "agriculture" \| "macro"	optional	Filter to a specific sector. Free tier is restricted to "energy".

Example Request

"Give me an overview of all commodity markets"

Example Response

json

{
  "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 }
  ]
}

get_weekly_digest

Pro+

Get an AI-generated weekly market digest with key events, signal summaries, and cross-sector analysis.

Parameters

Parameter	Type	Required	Description
week	string	optional	ISO week format "YYYY-Www" (e.g. "2026-W14"). Defaults to most recent completed week.
sector	"energy" \| "metals" \| "agriculture" \| "macro"	optional	Filter to a specific sector. Omit for cross-sector digest.

Example Request

"Give me last week's commodity market digest"

Example Response

json

{
  "week_start": "2026-03-31",
  "week_end": "2026-04-04",
  "sector": null,
  "summary": "Energy markets firmed on tightening supply signals as EIA reported a larger-than-expected crude draw of 2.1M barrels. Gold extended its rally to fresh highs on safe-haven flows amid tariff uncertainty. Agricultural markets were mixed with corn pressured by favorable planting weather while soybeans found support from strong Chinese crush margins.",
  "key_events": [
    "EIA crude stocks -2.1M bbl vs -0.8M expected (Wed)",
    "CFTC data showed managed-money net longs in gold at 18-month high (Fri)",
    "USDA prospective plantings report showed corn acreage above estimates",
    "WTI backwardation steepened to -$4.18 across front 12 months"
  ],
  "signals": [
    { "symbol": "CL", "name": "WTI Crude Oil", "sector": "energy", "composite_score": 68, "direction": "bullish", "confidence": "high", "report_date": "2026-04-04", "week_change": 4 },
    { "symbol": "GC", "name": "Gold", "sector": "metals", "composite_score": 74, "direction": "bullish", "confidence": "high", "report_date": "2026-04-04", "week_change": 2 }
  ],
  "generated_at": "2026-04-05T08:00:00Z"
}

#Tier Comparison

Feature	Free	Pro	Institutional
Tools	2 (signal + overview)	All 6	All 6
Sectors	Energy only	All	All
Data delay	7 days	Real-time	Real-time
Monthly calls	50	2,000	Unlimited
Burst limit	5/min	30/min	120/min
Custom weights	No	No	Yes
Raw export	No	No	JSON/CSV

#Custom Signal WeightsInstitutional

Institutional clients can override the default component weights per request via the custom_weights parameter on get_commodity_signal. Weights are auto-normalized to sum to 1.0, so you can pass any relative values.

Default Weights by Sector

Energy

EIA Supply/Demand35%

COT Positioning30%

Curve Structure25%

Seasonal Bias10%

Metals

Macro Context30%

COT Positioning20%

Curve Structure15%

Momentum15%

Seasonal Bias10%

Inventory10%

Agriculture

Seasonal Bias25%

COT Positioning20%

Inventory15%

Curve Structure15%

Macro Context15%

Momentum10%

Example: Custom Weights Request

json

{
  "name": "get_commodity_signal",
  "arguments": {
    "commodity": "CL",
    "custom_weights": {
      "cot_positioning": 0.50,
      "curve_structure": 0.30,
      "seasonal_bias": 0.20
    }
  }
}

Omitted components receive zero weight. The server normalizes provided values to sum to 1.0.

#Rate Limits & Caching

Burst Limits

Burst limits are enforced per 60-second sliding window. Free tier: 5 requests/min, Pro: 30/min, Institutional: 120/min. Exceeding the burst limit returns a 429 response with a retryAfter value in seconds.

Monthly Limits

Monthly call limits reset on the 1st of each month at midnight UTC. Free: 50 calls, Pro: 2,000 calls, Institutional: unlimited.

Caching

Responses are cached with TTLs aligned to upstream data release schedules:

•EIA Petroleum data — expires Wednesday 10:30 AM ET (release time)
•CFTC COT data — expires Friday 3:30 PM ET (release time)
•CME Settlements — expires next business day 5:00 PM ET
•Market Overview — 15-minute rolling TTL

Note: Cache hits still count against your rate limits. Rate limiting is applied before the cache layer, so both cached and uncached responses consume quota.