API Reference

MCP Server Documentation

Complete reference for the SupplyMaven MCP server. All tools, response formats, authentication, rate limits, and error handling.

Authentication

All requests require a Bearer token in the Authorization header. Keys are prefixed by tier:

Authorization: Bearer sm_free_abc123...   # Free tier key
Authorization: Bearer sm_live_xyz789...   # Pro / Signal key

Free Keys

Prefix: sm_free_. Generated instantly at /developers with just an email address. No credit card required.

Paid Keys

Prefix: sm_live_. Generated in Dashboard Settings after subscribing to Pro ($499/mo) or Signal ($999/mo).

Keys are hashed with SHA-256 before storage. The raw key is shown once at generation — it cannot be retrieved later. Regenerating a key immediately deactivates the previous one.

Endpoint

URL:       https://supplymaven.com/api/mcp
Protocol:  MCP (Model Context Protocol) over Streamable HTTP
Methods:   POST, GET, DELETE
Format:    JSON-RPC 2.0

The MCP server follows the Model Context Protocol specification. Compatible with Claude Desktop, Claude Code, ChatGPT, Cursor, Vercel AI SDK, LangChain, CrewAI, and any MCP-compatible client.

List available tools:

curl -X POST https://supplymaven.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sm_free_your_key" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Call a tool:

curl -X POST https://supplymaven.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sm_free_your_key" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "supply_chain_risk_assessment",
      "arguments": {}
    },
    "id": 2
  }'

Rate Limits

Free

100

requests / day

API Pro

10,000

requests / day

Bundle

25,000

requests / day

Rate limits reset daily. Each MCP tool call counts as one request. When the limit is exceeded, tools return:

Rate limit exceeded. Resets daily.

Enterprise plans with higher rate limits available on request — support@supplymaven.com

Error Responses

No API key or invalid key:

API key required. Get a free key instantly (no credit card) at https://supplymaven.com/developers

Rate limit exceeded:

Rate limit exceeded. Resets daily.

Free tier accessing paid-only tool:

Pillar scores are available on the API Pro plan.
Upgrade at supplymaven.com/subscribe

All error responses are returned as valid MCP tool results (not HTTP errors), so your agent handles them gracefully without connection failures.

Tool Reference

supply_chain_risk_assessment

Assess current global supply chain disruption risk. Returns the Global Disruption Index (GDI) — a real-time composite score from 0-100 measuring disruption across transportation, energy, materials, and macroeconomic pillars. Built from 200+ live data variables including port congestion, commodity prices, border delays, manufacturing output, and Federal Reserve economic indicators.

Parameters

None

Response Fields (Paid)

Global Disruption IndexExact score to one decimal (e.g. 58.4)

Data qualityGOOD, PARTIAL, or STALE

Needs attentionBoolean — true when GDI exceeds elevated threshold

Last updatedISO 8601 timestamp of most recent GDI calculation

Example Responses

Pro

Global Disruption Index: 58.4
Data quality: GOOD
Needs attention: true
Last updated: 2026-03-13T14:30:00.000Z

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Global Disruption Index: ~60 (rounded, 24h delayed)
Data quality: GOOD

Data provided by SupplyMaven | supplymaven.com/validation

---
Free tier: limited data. Upgrade to API Pro ($499/mo) for real-time, full-resolution data

The GDI recalculates every 15 minutes whenever new data arrives from any pillar. The free tier rounds to the nearest 5 and delays 24 hours to differentiate from paid real-time access.

risk_pillar_breakdown

Get detailed breakdown of supply chain disruption risk by category. Returns individual scores for each GDI pillar — Transportation (port congestion, border delays, freight weather), Energy (petroleum, natural gas, electricity, fuel prices), Materials (31 commodity prices with volatility), and Macro (Federal Reserve indicators, Producer Price Index). Each pillar includes its score, weight, and news boost.

Parameters

None

Response Fields (Paid)

TransportationScore 0-100, weight 30%, with news boost

EnergyScore 0-100, weight 25%, with news boost

MaterialsScore 0-100, weight 25%, with news boost

MacroScore 0-100, weight 20%, with news boost

Composite GDIWeighted average of all pillars

Example Responses

Pro

GDI Pillar Scores (0-100, higher = more risk):
  Transportation: 63.2 (weight: 30%, news boost: +2.4)
  Energy: 52.1 (weight: 25%, news boost: +1.8)
  Materials: 61.7 (weight: 25%, news boost: +3.1)
  Macro: 48.9 (weight: 20%, news boost: +0.5)
  Composite GDI: 58.4

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Pillar scores are available on the API Pro plan.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

News boost values reflect the additive points from disruption alerts scored and routed to each pillar. The composite GDI equals the weighted sum of pillar scores.

manufacturing_output_indicator

Detect US manufacturing output changes up to 24 hours before official government reports. The patent-pending Supply Manufacturing Index (SMI) analyzes weather-normalized electricity demand across 8 US power grid regions. Uses an inverted scale: lower values indicate stronger manufacturing activity. Ranges: 0-35 STRONG, 36-50 NORMAL, 51-65 BELOW TREND, 66+ WEAK.

Parameters

None

Response Fields (Paid)

NationalExact composite score with status

Regional BreakdownScore and status for each of 8 grid regions

Example Responses

Pro

Supply Maven Manufacturing Index (lower = stronger):
  National: 44.2 — NORMAL

Regional Breakdown:
  MISO: 41.3 (NORMAL)
  ERCO: 38.7 (NORMAL)
  PJM: 52.1 (BELOW TREND)
  SWPP: 40.5 (NORMAL)
  CISO: 46.8 (NORMAL)
  ISNE: 44.9 (NORMAL)
  NYIS: 48.2 (NORMAL)
  NW: 43.1 (NORMAL)

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Supply Maven Manufacturing Index: ~45 (rounded)
Status: NORMAL
Regional breakdown available on API Pro plan.

Data provided by SupplyMaven | supplymaven.com/validation

---
Free tier: limited data. Upgrade to API Pro ($499/mo) for real-time, full-resolution data

The 8 grid regions are GDP-weighted (PJM 22%, MISO 20%, ERCO 18%, CISO 14%, SWPP 10%, NYIS 8%, ISNE 5%, NW 3%) to compute the national composite. The SMI updates hourly as new electricity demand data arrives from the EIA.

commodity_price_monitor

Monitor real-time commodity prices and price volatility for supply chain cost management. Tracks 31 commodities across energy (WTI crude, Brent, natural gas), metals (copper, aluminum, nickel, zinc, lithium), agriculture (corn, wheat, soybeans), industrial materials (rubber, polyethylene), and semiconductor materials (germanium, gallium, indium).

Parameters

None

Response Fields (Paid)

All tracked commodities28+ commodities across all categories

Per commoditySymbol, price in USD, 24-hour change percent

Example Responses

Pro

Commodity Prices (28 tracked):
  WTIOIL: $68.42 (+1.23%)
  BRENTOIL: $72.18 (+0.89%)
  XCU: $4.12 (-0.34%)
  US-HRC: $680.00 (+0.15%)
  NG: $2.84 (-2.10%)
  XAL: $2,418.50 (+0.67%)
  GALLIUM: $412.00 (+3.20%)
  ...

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Commodity Prices (5 of 28 — free tier):
  WTIOIL: $68.42 (+1.23%)
  BRENTOIL: $72.18 (+0.89%)
  XCU: $4.12 (-0.34%)
  US-HRC: $680.00 (+0.15%)
  NG: $2.84 (-2.10%)

Data provided by SupplyMaven | supplymaven.com/validation

---
Free tier: limited data. Upgrade to API Pro ($499/mo) for real-time, full-resolution data

Commodity prices are fetched every 3 hours from Commodities-API. The change percentage reflects the 24-hour price movement. Prices are in USD. Commodities with no recent data show "N/A" instead of a price.

port_congestion_monitor

Monitor real-time port congestion and vessel traffic at 26 major global ports. Returns vessel counts at berth and at anchor, congestion score versus historical baseline, and port status. Covers US, Asian, and European ports.

Parameters

None

Response Fields (Paid)

portNamePort name

congestionScore0-100 score (higher = more congested)

congestionLevelLOW, MODERATE, HIGH, or CRITICAL

vesselCountTotal vessels currently in port area

stationaryVesselsVessels not moving (anchored or waiting)

Example Responses

Pro

Port Congestion (38 ports):
  Shanghai: score=72.4 level=HIGH vessels=142 stationary=48
  Singapore: score=61.8 level=MODERATE vessels=198 stationary=35
  Rotterdam: score=45.2 level=MODERATE vessels=87 stationary=12
  Los Angeles: score=38.9 level=LOW vessels=62 stationary=8
  Savannah: score=33.1 level=LOW vessels=41 stationary=5
  ...

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Port congestion data is available on the API Pro plan.
Covers 30+ major global ports with real-time vessel scanning.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Port congestion is scanned multiple times daily via the Datalastic vessel tracking API. Stationary vessels (anchored, waiting to berth) are a key congestion indicator — a high ratio of stationary-to-total vessels suggests port backup. All 38 ports are returned in a single response.

supply_chain_disruption_alerts

Get real-time supply chain disruption alerts from global news intelligence and event detection. Returns categorized alerts for port closures, trade policy changes, tariff actions, natural disasters, labor strikes, sanctions, and weather disruptions. Each alert includes severity level, affected supply chain stage, and risk score.

Parameters

None

Response Fields (Paid)

titleAlert headline

supplyChainStageSourcing, manufacturing, logistics, or distribution

riskScore0-100 severity score

Example Responses

Pro

Disruption Alerts (14):
  - Red Sea shipping rerouted after Houthi attacks [logistics] (risk: 92)
  - Taiwan Strait naval exercises disrupt chip supply routes [sourcing] (risk: 85)
  - US steel tariff expansion announced for Q2 [sourcing] (risk: 78)
  - Panama Canal drought restrictions ease slightly [logistics] (risk: 62)
  - German industrial output falls 2.1% MoM [manufacturing] (risk: 55)
  ...

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Disruption Alerts — CRITICAL only (2 of 14):
  - Red Sea shipping rerouted after Houthi attacks [logistics] (risk: 92)
  - Taiwan Strait naval exercises disrupt chip supply routes [sourcing] (risk: 85)

Data provided by SupplyMaven | supplymaven.com/validation

---
Free tier: limited data. Upgrade to API Pro ($499/mo) for real-time, full-resolution data

Alerts are sourced from GNews and enriched by Claude AI for risk scoring, pillar routing, and supply chain stage classification. The free tier filters to risk score >= 80 (CRITICAL severity). Up to 25 alerts are returned per call.

get_action_signals

Returns statistically validated leading indicator signals evaluated against live GDI and SMI data. Each signal is a Granger-causal relationship tested at p≤0.01 with directional accuracy ≥55%. Signals return ACTIVE (threshold crossed), WATCH (approaching threshold), or CLEAR (normal). CLEAR signals are filtered out — only ACTIVE and WATCH signals are returned. Paid tier only.

Parameters

None

Response Fields (Paid)

StatusACTIVE or WATCH (CLEAR signals filtered out)

TitleHuman-readable signal name

Predictor → TargetThe Granger-causal relationship

Lag descriptionLead time (e.g. '1 week lead', '3 month lead')

Directional accuracyHistorical percentage of correct direction calls

Current valueCurrent reading of the predictor

ThresholdThe level at which the signal becomes ACTIVE

Active countNumber of ACTIVE signals

Watch countNumber of WATCH signals

Example Responses

Pro

Action Signals — 3 ACTIVE, 4 WATCH (7 total triggered):

  [ACTIVE] Materials Stress → WTI Crude Oil
    GDI:Materials → WTI Crude Oil | 1 week lead | 57% directional accuracy | current: 71 index | threshold: 65

  [ACTIVE] Macro Stress → Gallium
    GDI:Macro → Gallium | 1 week lead | 55% directional accuracy | current: 68 index | threshold: 65

  [WATCH] Mid-Atlantic Manufacturing → New Orders Lead
    SMI:PJM (deterioration trigger) → Manufacturing New Orders | 3 month lead | 78% directional accuracy | current: 63 SMI score | threshold: 66

Signal statuses: ACTIVE = threshold crossed, act now. WATCH = approaching threshold, prepare.
All signals validated via Granger causality (p≤0.01) with directional accuracy ≥55%.

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Action signals are available on the API Pro plan.
Signals include validated Granger-causal lead relationships for crude oil, critical minerals, industrial production, and more.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Action signals are re-evaluated every GDI recalculation cycle (every 15 minutes). Each signal is backed by a Granger causality test with p≤0.01 and directional accuracy ≥55%. The 36 signals cover GDI pillar → commodity relationships, SMI → economic indicator relationships, and conditional triggers based on sustained threshold crossings.

get_border_delays

Get real-time commercial border crossing wait times at US-Mexico and US-Canada ports of entry. Returns current delay in minutes for commercial vehicles, port status, and summary statistics. Updated every 30 minutes from US Customs and Border Protection. Covers all major commercial crossings including Laredo, El Paso, Nogales, Otay Mesa, Detroit, Buffalo, and Blaine.

Parameters

border (optional: 'mexico' or 'canada'), crossing (optional: specific name)

Response Fields (Paid)

portNameBorder crossing name

bordermexico or canada

commercialDelayMinutesCurrent commercial vehicle wait in minutes

Summary statsAverage delay, high delay count, critical delay count

Example Responses

Pro

Border Crossing Delays (81 crossings):
  Laredo (mexico): commercial delay=45 min
  El Paso (mexico): commercial delay=32 min
  Otay Mesa (mexico): commercial delay=28 min
  Detroit (canada): commercial delay=12 min
  Buffalo (canada): commercial delay=8 min
  Blaine (canada): commercial delay=5 min
  ...

Avg delay: 22 min | High delay (>30min): 8 crossings | Critical (>60min): 2

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Border crossing delays are available on the API Pro plan.
Covers 80+ US-Mexico and US-Canada commercial crossings updated every 30 minutes.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Border wait times are sourced from US Customs and Border Protection (CBP) and update every 30 minutes. Data covers approximately 81 deduplicated crossings. The 'border' parameter filters to Mexico or Canada crossings. The 'crossing' parameter filters by name substring match.

get_chokepoint_traffic

Monitor real-time vessel traffic and congestion at critical maritime chokepoints — Suez Canal, Panama Canal, Strait of Malacca, Strait of Hormuz, Bab el-Mandeb, and other strategic waterways. Returns vessel counts, average speed, slow/stationary vessels, and congestion score with severity level.

Parameters

chokepoint (optional: 'suez', 'panama', 'malacca', etc.)

Response Fields (Paid)

chokepointNameName of the chokepoint

congestionScore0-100 score (higher = more congested)

congestionLevelNORMAL, ELEVATED, HIGH, or CRITICAL

totalVesselsTotal vessels in the chokepoint zone

slowVesselsVessels moving below normal speed

stationaryVesselsVessels not moving

avgSpeedAverage vessel speed in knots

Example Responses

Pro

Maritime Chokepoint Traffic (8 chokepoints, aggregate score: 42.5):
  Suez Canal: score=62.4 level=ELEVATED vessels=47 slow=5 stationary=2 avg_speed=8.2kn
  Panama Canal: score=51.3 level=ELEVATED vessels=32 slow=3 stationary=1 avg_speed=6.8kn
  Strait of Malacca: score=45.1 level=NORMAL vessels=89 slow=8 stationary=3 avg_speed=10.4kn
  Strait of Hormuz: score=38.7 level=NORMAL vessels=41 slow=2 stationary=0 avg_speed=11.1kn
  Bab el-Mandeb: score=35.2 level=NORMAL vessels=28 slow=1 stationary=0 avg_speed=9.7kn
  ...

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Maritime chokepoint traffic data is available on the API Pro plan.
Covers Suez Canal, Panama Canal, Strait of Malacca, Strait of Hormuz, and more.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Chokepoint data is aggregated from vessel tracking scans. Up to 12 chokepoints are monitored. The aggregate score is the weighted average across all chokepoints. When a chokepoint congests or closes, global shipping routes reroute within days.

get_air_cargo_disruptions

Get real-time air cargo disruption status at major US and international freight hub airports. Returns FAA ground delays, ground stops, arrival/departure delays, disruption scores, and traffic collapse detection. Covers 39 airports including Memphis (FedEx), Louisville (UPS), Anchorage, Chicago O'Hare, and others.

Parameters

airport (optional: IATA code like 'MEM', 'SDF', 'ORD')

Response Fields (Paid)

airportCodeIATA airport code

airportNameFull airport name

disruptionScore0-100 (higher = more disrupted)

disruptionLevelLOW, MODERATE, HIGH, or CRITICAL

hasGroundDelayWhether ground delay program is active

hasGroundStopWhether ground stop is active

hasArrivalDelayWhether arrival delays exist

hasDepartureDelayWhether departure delays exist

Example Responses

Pro

Air Cargo Disruptions (39 airports, 3 with elevated disruption):
  ORD (Chicago O'Hare International): score=72 level=HIGH
    Ground delay: avg 45min — weather/snow
    Arrival delay: up to 60min
  JFK (John F Kennedy International): score=61 level=MODERATE
    Departure delay: up to 30min
  MEM (Memphis International): score=35 level=LOW
  SDF (Louisville International): score=28 level=LOW
  LAX (Los Angeles International): score=25 level=LOW
  ...

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Air cargo disruption data is available on the API Pro plan.
Covers 39 major US and international cargo hub airports.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Airport status is sourced from the FAA and updates every 30 minutes. The disruption score factors in ground delays, ground stops, arrival/departure delays, and traffic volume compared to 30-day baselines. Traffic collapse detection flags when flight volumes drop significantly below baseline.

get_trade_policy_impacts

Get active trade policy actions currently impacting supply chain risk — tariffs, sanctions, export controls, import restrictions, and regulatory changes. Unlike news alerts that expire after 72 hours, policy adjustments persist and continue to modify GDI risk scores. Each policy includes the affected GDI pillar, score modifier, and effective duration.

Parameters

pillar (optional: 'transportation', 'energy', 'materials', 'macro')

Response Fields (Paid)

tierPolicy tier: SUSTAINED (7-30d with decay) or STRUCTURAL (no expiry)

pillarAffected GDI pillar

effectiveModifierCurrent score modifier in points (after decay)

descriptionPolicy description

ageDaysDays since policy was first detected

refreshCountNumber of times this policy was reinforced by new events

Example Responses

Pro

Active Trade Policy Impacts (5 policies):
  [SUSTAINED] ENERGY: +4.2 pts — Iran sanctions tightening restricts petroleum exports (age: 12d, refreshed 8x)
  [SUSTAINED] MATERIALS: +3.8 pts — China export controls on germanium and gallium (age: 45d, refreshed 22x)
  [STRUCTURAL] TRANSPORTATION: +2.5 pts — Red Sea shipping rerouting via Cape of Good Hope (age: 180d, refreshed 0x)
  [SUSTAINED] MACRO: +1.2 pts — US Section 301 tariff expansion on Chinese imports (age: 8d, refreshed 3x)
  [SUSTAINED] MATERIALS: +0.8 pts — EU carbon border adjustment mechanism phase-in (age: 25d, refreshed 1x)

Pillar score modifiers: ENERGY: +4.2, MATERIALS: +4.6, TRANSPORTATION: +2.5, MACRO: +1.2
Total active: 5

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Trade policy impact data is available on the API Pro plan.
Shows active tariffs, sanctions, and policy changes affecting each GDI pillar.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Policy adjustments are detected from news events with risk score >= 80 and US DIRECT relevance. SUSTAINED policies decay over 30 days: 1-7d=100%, 8-14d=75%, 15-21d=50%, 22-30d=25%. Policies that are continually refreshed by new events maintain their full modifier. STRUCTURAL policies have no expiry. Maximum 13 points per pillar from policy adjustments.

get_energy_breakdown

Get comprehensive US energy market status for supply chain cost analysis. Returns crude oil prices, natural gas spot (Henry Hub), retail fuel prices, natural gas storage, refinery utilization, petroleum stocks, and import/export flows. The disaggregated view behind the GDI Energy pillar.

Parameters

sector (optional: 'crude', 'naturalgas', 'fuel', 'refinery', 'storage', 'trade')

Response Fields (Paid)

Petroleum PricesWTI, Brent, and other crude benchmarks

Natural GasHenry Hub spot price

StorageNatural gas storage level, week-over-week change, capacity %

Retail FuelGasoline and diesel prices by region

RefineryUtilization rate, crude inputs, gasoline production

StocksCrude, gasoline, distillate stock levels with WoW changes

TradeImport/export volumes by product

Example Responses

Pro

US Energy Market Breakdown:

Petroleum Prices:
  Crude Oil WTI Spot: 68.42 $/barrel
  Crude Oil Brent Spot: 72.18 $/barrel

Natural Gas:
  Henry Hub spot: $2.84/MMBtu (2026-04-02)

Natural Gas Storage:
  Level: 1,842 Bcf (2026-03-28)
  Week-over-week change: +12 Bcf
  Capacity: 48.2%

Retail Fuel Prices:
  regular_gasoline (US): $3.284/gal (+0.012/gal WoW)
  diesel (US): $3.891/gal (-0.008/gal WoW)

Refinery Operations:
  utilization: 87.4 percent (2026-03-28)
  crude_inputs: 15,842 thousand bbl/day (2026-03-28)

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Energy breakdown data is available on the API Pro plan.
Covers crude oil, natural gas, retail fuel, refinery utilization, storage, and trade flows.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Energy data is sourced from the EIA and updates weekly for most series. The 'sector' parameter filters to a specific area. Without it, all sectors are returned in a single response.

get_rail_freight_status

Get US freight rail performance metrics from the Surface Transportation Board, Association of American Railroads, and USDA grain transportation reports. Covers train speed, terminal dwell time, carloadings, intermodal units, and grain transport rates with diesel price tracking.

Parameters

None

Response Fields (Paid)

avgTrainSpeedAverage train speed in mph

terminalDwellTimeAverage terminal dwell time in hours

carsOnLineTotal railcars on the network

trainsHeldPerDayTrains held in terminal per day

carsNotMoved48hCars not moved within 48 hours

totalCarloadsWeekly total carloadings

intermodalUnitsWeekly intermodal container units

grainRailRateGrain rail rate in $/car

dieselPriceDiesel price in $/gallon

Example Responses

Pro

US Freight Rail Status:

Railroad Service Metrics (STB):
  Date: 2026-03-28
  Avg train speed: 24.3 mph
  Terminal dwell time: 26.1 hours
  Cars on line: 1,245,000
  Trains held/day: 312
  Cars not moved 48h: 89,400

By Carrier:
  BNSF: speed=25.1mph dwell=24.8h
  UP: speed=23.8mph dwell=27.2h
  CSX: speed=24.5mph dwell=25.6h
  NS: speed=23.2mph dwell=26.9h

Rail Carloadings:
  Date: 2026-03-28
  Total carloads: 234,500
  Intermodal units: 287,000

Grain Transport:
  Grain rail rate: $4.12/car
  Grain truck rate: $3.87/mile
  Diesel price: $3.95/gal

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Rail freight data is available on the API Pro plan.
Covers train speed, dwell time, carloadings, intermodal, and grain transport rates.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

Rail metrics update weekly from STB railroad service reports, AAR carloading data, and USDA grain transportation reports. When train speed drops or dwell time increases, it signals freight network congestion that affects inland supply chains within days.

get_freight_transportation_index

Get the US freight transportation health index from the Bureau of Transportation Statistics. Returns the Transportation Services Index (TSI) for freight and passenger, truck tonnage, rail carloadings, rail intermodal volume, waterborne freight, and inventory-to-sales ratio.

Parameters

None

Response Fields (Paid)

tsiFreightFreight Transportation Services Index

tsiFreightChangeMonth-over-month change %

truckTonnageTruck tonnage index

railCarloadsRail carloads index

railIntermodalRail intermodal index

waterborneWaterborne freight index

invToSalesInventory-to-sales ratio

3-month trendTSI freight trend direction

Example Responses

Pro

US Freight Transportation Index (BTS):
  Date: 2026-02
  Freight TSI: 141.2 (+0.8%)
  Passenger TSI: 128.4
  Total TSI: 136.7
  3-month trend: +2.1%

  Truck tonnage index: 118.4
  Rail carloads index: 105.2
  Rail intermodal index: 112.8
  Waterborne index: 98.6
  Inventory-to-sales ratio: 1.35

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Freight transportation index data is available on the API Pro plan.
Covers TSI, truck tonnage, rail carloadings, intermodal, and waterborne freight.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

BTS freight data updates monthly, typically with a 2-month lag. The TSI is a broad measure of freight demand across all modes. Declining freight volumes are a leading indicator of economic slowdown.

get_economic_indicators

Get key economic indicators affecting supply chain costs and conditions. Returns Federal Reserve data (industrial production, capacity utilization, manufacturing PMI), Producer Price Index by category, Global Supply Chain Pressure Index (GSCPI) from the NY Fed, and EIA Short-Term Energy Outlook forecasts.

Parameters

category (optional: 'fred', 'ppi', 'gscpi', 'steo')

Response Fields (Paid)

FRED indicatorsIndustrial production, capacity utilization, manufacturing, PPI, dollar index, imports, housing

PPI by categoryProducer prices for materials, metals, chemicals, construction, manufacturing

GSCPINY Fed Global Supply Chain Pressure Index with interpretation

STEOEIA macro forecasts with actual vs. forecast flag

Example Responses

Pro

Economic Indicators:

Federal Reserve Data (FRED):
  Industrial Production (INDPRO): 103.8 (2026-02)
  Capacity Utilization (MCUMFN): 77.2 (2026-02)
  Manufacturing Production (IPGMFN): 98.4 (2026-02)
  Producer Price Index (PPIACO): 268.1 (2026-02)
  Dollar Index (DTWEXBGS): 124.5 (2026-03-28)
  Manufacturing IP (IPMAN): 96.2 (2026-02)

Producer Price Index (BLS):
  Iron and steel: 342.1 (+1.2%) (2026-02)
  Industrial chemicals: 285.4 (-0.8%) (2026-02)
  Construction materials: 312.7 (+0.3%) (2026-02)

Global Supply Chain Pressure Index (NY Fed):
  GSCPI: 0.42 (2026-02)
  Interpretation: Slightly above normal

EIA Short-Term Energy Outlook (Macro):
  Real GDP Growth: 2.1 (2026-Q1, actual)
  CPI Energy: 248.3 (2026-03, forecast)

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Economic indicator data is available on the API Pro plan.
Covers FRED, PPI, GSCPI, and EIA STEO forecasts.
Upgrade at supplymaven.com/subscribe

Data provided by SupplyMaven | supplymaven.com/validation

FRED data updates on government publication schedules (monthly for most series). PPI updates monthly from BLS. GSCPI updates monthly from NY Fed. STEO updates monthly on the 13th, with both historical actuals and forward-looking forecasts.

get_predictive_signals

Get statistically validated leading indicator signals evaluated against live supply chain data. 58 Granger-causal signals predict commodity price movements, manufacturing shifts, and macroeconomic changes 1 week to 6 months ahead. Returns ACTIVE (threshold crossed), WATCH (approaching threshold), or CLEAR status.

Parameters

tier (optional: 1, 2, or 3), status (optional: 'TRIGGERED', 'PENDING', 'CLEAR'), group (optional: predictor group like 'GDI:Energy')

Response Fields (Paid)

Signal statusACTIVE (triggered), WATCH (pending), or CLEAR for each signal

Predictor → TargetWhich index predicts which outcome (e.g. GDI:Energy → Gasoline prices)

Lag timeHow far ahead the signal predicts (1 week to 6 months)

Directional accuracyHistorical accuracy of signal direction predictions (55%+)

Current / ThresholdCurrent predictor value vs. threshold that triggers the signal

Example Responses

Signal ($999/mo)

Predictive Signals — 3 ACTIVE, 4 WATCH, 51 CLEAR (58 total monitored):

ACTIVE (threshold crossed — act now):
  [ACTIVE] Materials Stress → WTI Crude Oil
    GDI:Materials → WTI Crude Oil | 1 week lead | 57% directional accuracy | current: 71.0 | threshold: 65.0
  [ACTIVE] Energy Stress → Retail Gasoline
    GDI:Energy → GASREGCOVW | 2 week lead | 68% directional accuracy | current: 74.2 | threshold: 60.0

WATCH (approaching threshold — prepare):
  [WATCH] PJM Manufacturing → New Orders Lead
    SMI:PJM → Manufacturing New Orders | 3 month lead | 78% directional accuracy | current: 63.1 | threshold: 66.0

CLEAR: 51 signals within normal range.

Signal statuses: ACTIVE = threshold crossed, act now. WATCH = approaching threshold, prepare.
All signals validated via Granger causality (p<=0.01) with directional accuracy >=55%.

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Predictive signals require Signal tier ($999/mo). 58 Granger-causal signals with ACTIVE/WATCH/CLEAR status, lag times, and directional accuracy — plus all 15 Pro tools. Upgrade → supplymaven.com/subscribe

Signals are evaluated every 15 minutes against live GDI and SMI data. Tier 1 signals have the highest statistical confidence and longest validation history. Use the tier parameter to focus on the most reliable signals.

get_manufacturing_anomalies

Detect unusual electricity demand patterns signaling manufacturing disruptions before they appear in official reports. Returns current SMI score with regional breakdown plus demand anomalies from the past 7 days ranked by severity. Patent-pending weather normalization isolates industrial demand.

Parameters

region (optional: PJM, MISO, ERCO, CISO, SWPP, ISNE, NYIS, NW), minSeverity (optional: LOW, MEDIUM, HIGH, CRITICAL — default: MEDIUM)

Response Fields (Paid)

National SMICurrent national manufacturing score (lower = stronger)

Regional breakdownPer-region score, status, and GDP weight for 8 grid regions

Anomaly severityLOW, MEDIUM, HIGH, or CRITICAL classification

Z-scoreStatistical deviation from historical mean demand

Demand vs. meanActual MW demand versus historical mean MW

Example Responses

Signal ($999/mo)

Supply Manufacturing Index (lower = stronger manufacturing):
  National: 44.2 — NORMAL

Regional Breakdown:
  PJM: 52.1 (BELOW TREND) — weight: 22%
  MISO: 41.3 (NORMAL) — weight: 20%
  ERCO: 38.7 (NORMAL) — weight: 18%
  CISO: 46.8 (NORMAL) — weight: 14%

Demand Anomalies (last 7 days, 3 detected):
  [HIGH] PJM at 2026-04-02T08:30 — z-score: 2.41 88th pctile
    demand: 42100 MW vs historical mean: 38200 MW
  [MEDIUM] ERCO at 2026-04-01T14:15 — z-score: 1.87 79th pctile
    demand: 51800 MW vs historical mean: 48400 MW

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Manufacturing anomaly detection requires Signal tier ($999/mo). Patent-pending SMI with 8-region breakdown and real-time demand anomalies — plus all 15 Pro tools. Upgrade → supplymaven.com/subscribe

SMI uses an inverted scale: lower scores = stronger manufacturing. Weather normalization removes seasonal demand (heating/cooling) so anomalies represent genuine industrial shifts. Anomalies update in near-real-time from EIA hourly electricity demand.

get_supply_chain_weekly_brief

Executive-level weekly supply chain situation report. Combines GDI score with pillar breakdown and trend, manufacturing output status, port congestion summary, active predictive signals, top disruption events, and key takeaways in a single comprehensive call.

Parameters

None

Response Fields (Paid)

GDI overviewCurrent score, all 4 pillar scores with weights, 7-day trend direction

Manufacturing (SMI)National score with top regional breakdowns

Port congestionTransportation index, ports reporting, elevated port count

Predictive signalsACTIVE/WATCH/CLEAR counts with top triggered signals

Disruption eventsTop 5 active news events by risk score and pillar

Key takeawaysPre-computed summary bullets from GDI analysis

Example Responses

Signal ($999/mo)

=== SUPPLY CHAIN WEEKLY BRIEF ===
Generated: 2026-04-04

── GLOBAL DISRUPTION INDEX ──
  Current GDI: 58.4/100 (NEEDS ATTENTION)
  Transportation: 62.1 (30% weight)
  Energy: 55.8 (25% weight)
  Materials: 58.2 (25% weight)
  Macro: 52.3 (20% weight)
  7-day trend: RISING (+3.2)

── MANUFACTURING OUTPUT (SMI) ──
  National SMI: 44.2 — NORMAL (lower = stronger)
  PJM: 52.1
  MISO: 41.3
  ERCO: 38.7
  CISO: 46.8

── PORT CONGESTION ──
  Transportation Index: 48.2/100 — NORMAL
  Ports reporting: 26 | Elevated+: 4

── PREDICTIVE SIGNALS ──
  3 ACTIVE | 4 WATCH | 51 CLEAR (58 monitored)
  [ACTIVE] Materials Stress → WTI: GDI:Materials → WTI Crude Oil
  [ACTIVE] Energy Stress → Gasoline: GDI:Energy → GASREGCOVW

── TOP DISRUPTION EVENTS ──
  [ENERGY] Iran sanctions tighten crude supply — risk: 88/100
  [TRANSPORTATION] Panama Canal draft restrictions — risk: 72/100
  [MATERIALS] China rare earth export controls — risk: 68/100

── KEY TAKEAWAYS ──
  • Energy pillar elevated due to Middle East geopolitical risk
  • Manufacturing output stable nationally despite PJM weakness
  • 3 predictive signals triggered — review commodity exposure

Data provided by SupplyMaven | supplymaven.com/validation

Free tier

Weekly supply chain brief requires Signal tier ($999/mo). Executive-level situation report combining GDI, SMI, commodities, ports, signals, and disruption events — plus all 15 Pro tools. Upgrade → supplymaven.com/subscribe

This is the most comprehensive single-call tool. Designed for weekly stakeholder briefings and executive dashboards. Combines data from 6+ internal data sources into one structured report.

get_signal_narratives

Get plain-language explanations of active predictive signals. Each narrative explains the mechanism — why the predictor leads the target, what economic logic connects them, and what the current reading implies. Designed for non-quantitative users.

Parameters

signalId (optional: specific signal ID like 'SIG-1')

Response Fields (Paid)

StatusCurrent signal status (active, pending_outcome)

MechanismEconomic logic connecting predictor to target

NarrativeFull-text explanation of current signal implications

Trigger contextPredictor value, direction, target label

Example Responses

Signal ($999/mo)

Signal Narrative: SIG-1
Status: active
Target: WTI Crude Oil
Direction: rising
Predictor Value: 71.2
Mechanism: Materials stress historically precedes crude oil price increases as supply constraints propagate through the energy complex.

When the GDI Materials pillar exceeds 65, it has historically led to WTI crude price increases within 1 week with 57% directional accuracy. The current reading of 71.2 significantly exceeds the threshold, suggesting upward pressure on crude oil prices in the near term.

Generated: 2026-04-04T14:00:00.000Z

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

Signal narratives require Signal tier ($999/mo). Plain-language explanations of predictive signals with economic mechanism analysis — plus all Pro tools. Upgrade → supplymaven.com/subscribe

Narratives are generated when signals trigger and cached. If no narrative exists for a signal, it means the signal hasn't fired recently.

get_energy_forecast

Get the EIA Short-Term Energy Outlook (STEO) — official government forecasts for energy production, consumption, and pricing. Returns both historical actuals and forward-looking projections with isActual flag.

Parameters

category (optional: 'prices', 'petroleum', 'natural_gas', 'electricity', 'macro'), forecast_only (optional: boolean)

Response Fields (Paid)

Series nameSTEO series label (e.g. WTI Crude Oil Price)

ValueLatest value for the series

DatePeriod (YYYY-MM format)

isActualtrue = historical data, false = government projection

UnitsMeasurement units for the series

Example Responses

Signal ($999/mo)

EIA Short-Term Energy Outlook — prices (8 series):

  WTI Crude Oil Price (dollars per barrel): 72.40 [2026-03, actual]
  Brent Crude Oil Price (dollars per barrel): 76.10 [2026-03, actual]
  Henry Hub Natural Gas Price (dollars per mcf): 3.85 [2026-03, actual]
  Retail Gasoline Price (dollars per gallon): 3.42 [2026-04, forecast]
  Retail Diesel Price (dollars per gallon): 3.78 [2026-04, forecast]

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

EIA energy forecasts require Signal tier ($999/mo). Official STEO projections for crude oil, natural gas, electricity, and more. Upgrade → supplymaven.com/subscribe

STEO updates monthly on the 13th. Data covers 2019 to ~18 months ahead. Use forecast_only=true to see only projected values.

get_gdi_trend_analysis

Get trend analysis of the Global Disruption Index over time. Current score plus period comparison with direction, velocity of change (accelerating/decelerating), and pillar-level momentum.

Parameters

period (optional: '7d', '14d', '30d', '90d' — default: '30d')

Response Fields (Paid)

Current GDILatest score out of 100

Period trendStart → end value with direction

VelocityAccelerating, decelerating, or steady

Pillar scoresCurrent reading for each of 4 pillars

Primary driverPillar contributing most to current score

Example Responses

Signal ($999/mo)

=== GDI TREND ANALYSIS (30-day) ===

Current GDI: 58.4/100

Trend:
  Period start: 45.2 → Current: 58.4
  Change: +13.2 (RISING)
  Velocity: accelerating
  Data points: 30

Pillar Scores (current):
  Transportation: 62.1 (30% weight)
  Energy: 55.8 (25% weight)
  Materials: 58.2 (25% weight)
  Macro: 52.3 (20% weight)

  Primary driver: Transportation (62.1)

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

GDI trend analysis requires Signal tier ($999/mo). Risk trend direction, velocity, acceleration, and pillar momentum. Upgrade → supplymaven.com/subscribe

Uses daily index snapshots for trend calculation. Velocity is computed by comparing rate of change in first vs. second half of the period.

get_commodity_volatility_alerts

Get alerts for commodities experiencing abnormal price volatility. Flags commodities where 24-hour price changes exceed a configurable threshold.

Parameters

threshold (optional: minimum absolute 24h change % — default: 2.0), category (optional: 'energy', 'metals', 'agriculture', 'industrial', 'semiconductors')

Response Fields (Paid)

CommodityName and symbol

DirectionUP or DOWN

PriceCurrent price

24h changePercentage change in last 24 hours

CategoryCommodity category

Example Responses

Signal ($999/mo)

Commodity Volatility Alerts (threshold: ±2.0% 24h change):

3 commodities flagged:

  [UP] Copper (XCU) — metals
    Price: 4.52 | 24h change: +3.85%
  [DOWN] Natural Gas (NG) — energy
    Price: 2.18 | 24h change: -4.12%
  [UP] Corn (CORN) — agriculture
    Price: 4.87 | 24h change: +2.34%

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

Commodity volatility alerts require Signal tier ($999/mo). Abnormal price movement detection across 31 commodities. Upgrade → supplymaven.com/subscribe

Uses live commodity_prices data. Threshold is configurable — lower values return more alerts. Sorted by absolute change descending.

get_port_congestion_trends

Get port congestion trend analysis — direction and trajectory versus historical baselines. Identifies ports where congestion is above or below baseline.

Parameters

port (optional: port name), threshold (optional: minimum deviation % from baseline — default: 10)

Response Fields (Paid)

PortPort name

Current scoreCongestion score (0-100)

Congestion levelLOW/NORMAL/ELEVATED/HIGH/CRITICAL

Baseline deviationPercentage above or below historical baseline

Vessel countCurrent vessels at port

Example Responses

Signal ($999/mo)

Port Congestion Trends (threshold: ±10% from baseline):

Congestion ABOVE baseline (4 ports):
  Shanghai: score 72.3 (HIGH) — +31% above baseline | 89 vessels
  Busan: score 61.5 (ELEVATED) — +22% above baseline | 45 vessels
  Los Angeles: score 58.1 (ELEVATED) — +15% above baseline | 38 vessels
  Rotterdam: score 55.4 (ELEVATED) — +12% above baseline | 52 vessels

Congestion BELOW baseline (2 ports):
  Singapore: score 38.2 (NORMAL) — -8% below baseline | 112 vessels

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

Port congestion trends require Signal tier ($999/mo). Congestion trajectory analysis for 26 global ports. Upgrade → supplymaven.com/subscribe

Compares current commercial congestion scores against port-specific historical baselines. Threshold filters out ports with minor deviations.

get_intelligence_briefs

Get AI-generated intelligence briefs for each supply chain dimension — energy, materials, transportation, macro, and manufacturing. Narrative analysis generated every hour from live data.

Parameters

type (optional: 'energy', 'materials', 'transport', 'macro', 'manufacturing')

Response Fields (Paid)

Brief typeSupply chain dimension

Executive summaryNarrative analysis of current conditions

Generated atWhen the brief was last generated

FreshnessWhether brief is current or expired

Example Responses

Signal ($999/mo)

Intelligence Brief: ENERGY
Generated: 45 minutes ago

Energy markets are moderately elevated. Natural gas storage drew down 12 Bcf last week versus an expected build, pushing spot prices to a 3-week high. Crude oil remains range-bound at $72/bbl. Retail fuel prices stable nationally but refinery utilization dipped to 88.2% — worth monitoring for potential supply tightening.

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

Intelligence briefs require Signal tier ($999/mo). AI-generated hourly analytical briefs per supply chain dimension. Upgrade → supplymaven.com/subscribe

Briefs are generated by Claude AI from live data every 60 minutes. Each brief covers current conditions, key drivers, emerging risks, and watch items. 5 dimensions available plus air-cargo.

get_weekly_content_package

Get the weekly 'Signal of the Week' content package — a pre-written, data-verified marketing bundle generated every Monday from live SupplyMaven data. Returns a Substack article (~500 words), LinkedIn post (~200 words), and Twitter/X thread (4-5 tweets), all built from verified supply chain data. Every number in the content traces back to a live data source. Designed for automated content distribution via Claude Desktop + platform MCP servers.

Parameters

None

Response Fields (Paid)

weekOfISO Monday date for the content week (e.g. 2026-03-30)

Signal of the WeekHeadline, data source, and data snapshot for the lead story

Data contextGDI score/trend, SMI score/status, top commodity, active signals, port anomalies, critical news

Substack article~500-word markdown article with title, signal lead, data context, and What to Watch section

LinkedIn post~200-word professional post with data points and hashtags

Twitter thread4-5 tweets: hook, context, implications, data, CTA

Example Responses

Signal ($999/mo)

=== SIGNAL OF THE WEEK (2026-03-30) ===

Headline: Tier 1 Signal Fired: SIG-NEW-013
Data Source: Signal Log — SIG-NEW-013

── DATA CONTEXT ──
GDI: 70.0 (STABLE)
SMI: 59.0 (BELOW_TREND)
Top Commodity: Polyethylene -1.42%
Active Signals: [T1] SIG-NEW-013, [T1] SIG-NEW-012, [T1] SIG-NEW-010
Port Alerts: Taiwan Strait (84), Shanghai (75), Bosphorus Strait (71)

══════════════════════════════════════
SUBSTACK ARTICLE:
══════════════════════════════════════
# Five Tier 1 Signals Fire as Middle East Tensions Grip Global Supply Lines

**Signal of the Week: SIG-NEW-013**

SupplyMaven's monitoring network has triggered an unprecedented five
simultaneous Tier 1 signals this week...
[~500 words of markdown-formatted article]

══════════════════════════════════════
LINKEDIN POST:
══════════════════════════════════════
Five Tier 1 signals firing simultaneously — the most critical alert
level in SupplyMaven's predictive monitoring system...
[~200 words with hashtags]

══════════════════════════════════════
TWITTER THREAD:
══════════════════════════════════════
[1/5] ALERT: Five Tier 1 signals just fired simultaneously...
[2/5] Our Global Disruption Index stands at 70.0/100...
[3/5] What it means: Taiwan Strait (84/100), Shanghai (75/100)...
[4/5] The data: Manufacturing Index at 59.0 (below trend)...
[5/5] Follow @SupplyMaven for weekly signals...

Data provided by SupplyMaven | supplymaven.com/validation

Free / Pro tier

Weekly content packages require Signal tier ($999/mo). AI-generated marketing content from live supply chain data — plus all 15 Pro tools, intelligence briefs, and 25,000 queries/day. Upgrade → supplymaven.com/subscribe

Content packages are generated weekly on Mondays at 10 AM ET via a scheduled cron. Every statistic in the generated content is verified against the data snapshot — no hallucinated numbers. The Signal of the Week is selected by ranking: GDI movement > T1 signal > commodity shock > port spike > SMI status change > critical news > pillar overview.

Data Freshness

GDI Composite

Every 15 minutes

Recalculates whenever any pillar receives new data

Electricity Demand (SMI)

Hourly

From EIA grid operator data

Commodity Prices

Every 3 hours

28+ commodities across energy, metals, and industrial categories

Port Congestion

Multiple times daily

Datalastic vessel position scanning for 38 ports

Disruption Alerts

Every 30 minutes

GNews + Claude AI enrichment for risk scoring

FRED Economic Data

Daily

On government publication schedule (PPI, employment, production)

EIA Sector Ratios

Monthly

Industrial vs commercial electricity demand by state

Content Packages

Weekly (Monday)

AI-generated Signal of the Week with Substack, LinkedIn, and Twitter content

MCP Server Documentation

Authentication

Endpoint

Rate Limits

Error Responses

Tool Reference

Data Freshness

On This Page