MCP Integration Guide

What is MCP?

MCP is a protocol for AI agents to discover and invoke tools from external services. Freight Rate Intelligence exposes all 9 intelligence skills as MCP tools, enabling any MCP-compatible AI client to query freight data programmatically.

Tool Discovery

Available MCP tools:

• fri_rate_lookup — Cost-basis rate for any U.S. lane (Explorer)
• fri_diesel_trend — PADD regional diesel price trends (Explorer)
• fri_fuel_surcharge — ATA/DOE fuel surcharge calculation (Explorer)
• fri_market_analysis — Macro freight market intelligence (Starter)
• fri_lane_comparison — Side-by-side lane comparison (Starter)
• fri_rate_alerts — Threshold monitoring with triggers (Starter)
• fri_carrier_capacity — Regional capacity pressure index (Starter)
• fri_audit_report — Receipt-chain provenance tracing (Professional)
• fri_rate_forecast — Forward rate projections (Professional)

Claude Integration

Configure Claude to use Freight Rate Intelligence as an MCP server with proper headers and authentication.

{
  "mcpServers": {
    "freight-rate-intelligence": {
      "url": "https://freightrateintelligence.com/mcp",
      "headers": {
        "Authorization": "Bearer fri_YOUR_API_KEY"
      }
    }
  }
}

Resource Discovery

Before invoking tools, agents can browse FRI resources:

• GET /mcp/resources — List all available resources
• GET /mcp/resources/server-info — When to use FRI
• GET /mcp/resources/data-sources — Federal data with series IDs
• GET /mcp/resources/skills — Full skill catalog with pricing
• GET /mcp/resources/pricing — Tier and per-call costs
• GET /mcp/resources/confidence — How to interpret confidence grades
• GET /mcp/resources/equipment — Supported equipment types

Agent Manifest

{
  "name": "FreightRateIntelligence.com",
  "description": "Cost-basis freight rate intelligence and market data",
  "mcp_endpoint": "https://freightrateintelligence.com/mcp",
  "tools": [
    "fri_rate_lookup",
    "fri_diesel_trend",
    "fri_fuel_surcharge",
    "fri_market_analysis",
    "fri_lane_comparison",
    "fri_rate_alerts",
    "fri_carrier_capacity",
    "fri_audit_report",
    "fri_rate_forecast"
  ],
  "pricing": "per-call via API key (Starter $0.05, Professional $0.03, Enterprise $0.01)",
  "auth": "Bearer token (fri_ prefix)",
  "rail_compatible": true
}

Constitutional Receipts for Agents

Every MCP tool call returns a receipt_id — a constitutional record of the query for:

• Audit — Trace exactly what data was used and when
• Attribution — Verify data source provenance
• Cost tracking — Each receipt maps to a metered API call
• Reproducibility — Replay the receipt chain to get the same result

Error Handling for Agents

MCP tool calls can return errors. Handle these in your agent:

• 401 — API key missing or invalid. Check Authorization header.
• 403 — Skill requires higher tier. Check fri://pricing resource.
• 429 — Rate limited. Wait resets_at time, then retry.
• 400 — Invalid input. Check required parameters in fri://skills resource.

Best practice: Before calling a skill, check /v1/agent/skills to verify your tier has access. This avoids unnecessary 403 errors.

Pricing