AI Agents / MCP

MCP Server — connect AI to live logistics data

Integrate FreightPulse with Claude, Cursor, ChatGPT, or any MCP-compatible assistant. Query fuel prices, freight rates, port congestion, disruptions, and carrier data straight from your AI conversation.

Get API key Getting started

Ask Claude

> "Is the Port of Los Angeles congested right now?"

AI calls MCP tool:
{
  "tool": "get_port_congestion",
  "params": { "port": "Los Angeles" }
}

8 MCP tools — fuel, rates, ports,
disruptions, carriers, history.

What is MCP and why does it matter?

The Model Context Protocol (MCP) lets AI assistants call external tools in real time. Instead of a training-data snapshot, your AI can fetch live logistics data from FreightPulse — just by asking a question.

Live logistics data

Fuel prices, freight rates, port congestion, disruptions, and carrier lookups — the same data behind the REST API.

Natural language

Ask "Show US diesel prices by region" and the agent picks the right tool and parameters automatically.

Same API quota

MCP calls use your existing FreightPulse plan — each tool call counts as one API request, no separate billing.

Available MCP tools

Eight tools: six map to real data endpoints, two (register, account_status) manage credentials.

TOOL get_fuel_prices Latest weekly average US diesel and gasoline prices by PADD region (source: EIA). No parameters, works on the guest tier. Maps to GET /api/v1/fuel-prices.

TOOL get_freight_rates Freight rate quote: trucking (ZIP-to-ZIP) or a limited set of Asian-origin ocean/air lanes. A 200 response can still mean "no quote found" — check data.available. Maps to GET /api/v1/freight-rates.

TOOL get_port_congestion Port-call activity vs. a 90-day baseline for major ports (source: IMF PortWatch). Pass at least one of port, country, or region. Maps to GET /api/v1/port-congestion.

TOOL get_disruptions Active natural-hazard disruptions merged from GDACS/USGS/NOAA. Covers weather and geological events only, not strikes or geopolitics. Maps to GET /api/v1/disruptions.

TOOL search_carriers US trucking carrier lookup (FMCSA SAFER, q required) or ocean NVOCC/OTI directory search (FMC, q optional). Maps to GET /api/v1/carriers.

TOOL get_historical_data Weekly time series for fuel prices or curated port-congestion metrics, by period or explicit date range. Maps to GET /api/v1/historical.

TOOL register Self-register an account with no human sign-up form and no credit card. Returns a working API key on the perpetual free tier (100 req/month). Rate-limited to 5 registrations/day per IP.

TOOL account_status Check the current key’s plan, usage, and quota — call this before assuming the API is broken on a 429 or 403.

Getting started

One URL for every client. Works immediately with no key on the 100 requests/day guest tier (shared by IP).

MCP endpoint

https://mcp.freightpulsehq.com/mcp

Authentication

For a private quota instead of the guest tier, authenticate with a real API key three ways:

Authorization: Bearer YOUR_KEY header — works if your client supports custom headers.
X-API-Key: YOUR_KEY header — identical, alternate header name.
?apikey=YOUR_KEY on the URL — only for a client that keeps query strings and cannot set headers. Claude Desktop and claude.ai strip it. Do not use npx or mcp-remote.

No key yet? Call the register tool from inside the agent — no sign-up form, no card, returns a working free-tier key immediately. As a human: one-click setup if you’re logged in, or create a free account and grab a key from the dashboard.

Connect to Claude

Claude Desktop / claude.ai use a custom connector. There’s no OAuth "Authorize" screen on FreightPulse yet — add the connector with no authentication (guest tier), or use Claude Code below to send a real key.

Open Connectors: Settings → Connectors → Add custom connector.

Name: FreightPulse Remote server URL: https://mcp.freightpulsehq.com/mcp

Authentication: leave as "No authentication" to use the guest tier. Once connected, ask the agent to call register for your own free-tier key, or paste the value from step 2 above into a header if the client supports it.

Connect with Claude Code (CLI)

Pass the key as a header. Leave it off to stay on the guest tier, then ask Claude to call register.

bash

claude mcp add --transport http freightpulse https://mcp.freightpulsehq.com/mcp --header "Authorization: Bearer YOUR_KEY"

Connect to Cursor

Add an entry to ~/.cursor/mcp.json (or .cursor/mcp.json in a project for a project-only setup), then restart Cursor.

mcp.json

{
  "mcpServers": {
    "freightpulse": {
      "url": "https://mcp.freightpulsehq.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Omit headers to stay on the guest tier. Cursor can also add the server from Settings → MCP with the same URL.

Connect to ChatGPT

In ChatGPT, open Settings → Connectors and add a custom MCP connector with Remote server URL: https://mcp.freightpulsehq.com/mcp. Do not proxy that URL through the OpenAI API. There is no OAuth screen, so it connects on the guest tier — ask it to call register for a private key.

Try: "What's the current US diesel price?" or "Any active disruptions near the Port of Long Beach?"

curl example

Raw JSON-RPC 2.0 over HTTP, if you’re not going through an MCP client:

bash

curl -X POST "https://mcp.freightpulsehq.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_fuel_prices",
      "arguments": {}
    }
  }'

Frequently asked questions

Prefer a header: Authorization: Bearer YOUR_KEY or X-API-Key: YOUR_KEY. ?apikey= works only on clients that keep the query string — Claude Desktop and claude.ai strip it, so do not use it to connect Claude. No key at all still works on the 100 requests/day guest tier. Don’t have a key? Call the register tool (it runs the OAuth client-credentials signup and returns a free-tier key). There is no browser Authorize screen. Or create a free account.

MCP calls count toward the same quota as REST API calls — one tool call equals one API request. The free tier is 100 requests/month, 5/minute; see the docs for paid plans.

Six data tools cover fuel prices, freight rates, port congestion, disruptions, carrier lookups, and historical data, plus register and account_status for credential management. See Available Tools above.

Yes — any client that speaks the Model Context Protocol over Streamable HTTP can connect: Cursor, ChatGPT connectors, custom Python/Node clients, and anything MCP-compatible going forward.

No. register calls POST /oauth/register and POST /oauth/token (client credentials) and hands back an API key. That is not a browser Authorize screen, and there is no public client ID to paste into Claude. Send the key as a header afterwards.

Full parameter reference: mcp.freightpulsehq.com/llms-full.txt. REST API docs: https://freightpulsehq.com/docs. Machine-readable auth guide: /auth.md.