Flow Engine MCP quickstart

1. Get a key

Sign up with your email, save a card (via Stripe; nothing is charged), and create a key on the dashboard. Keys look like vrf_dev_... and are shown exactly once. You start with $20 of free credit (valid 30 days). Pricing: $2.25 per fuel plan and $0.08 per replan of the same trip; prepaid credit never expires. Only successful optimizations are charged — validation errors, unroutable requests, and internal failures are free.

2. Connect a client

Claude Code

claude mcp add --transport http flow-engine \
  https://app.valverideflow.com/api/mcp \
  --header "Authorization: Bearer vrf_dev_YOUR_KEY"

Claude Desktop, Cursor, or any JSON-config client

{
  "mcpServers": {
    "flow-engine": {
      "type": "http",
      "url": "https://app.valverideflow.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vrf_dev_YOUR_KEY"
      }
    }
  }
}

Endpoint: https://app.valverideflow.com/api/mcp. The server is stateless JSON (no SSE stream, no session ids). initialize and tools/list work without a key so you can inspect the tool; tools/call requires the bearer key.

3. Call the tool

From an agent, just ask for a fuel plan; the tool schema guides the model. Under the hood (or from raw HTTP) a call looks like:

curl -X POST https://app.valverideflow.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vrf_dev_YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "optimize_fuel_plan",
      "arguments": {
        "truck": { "tankCapacityGallons": 240, "mpgForPlanning": 6.5 },
        "currentFuelGallons": 80,
        "origin": { "lat": 41.6, "lng": -93.6 },
        "destination": { "lat": 39.74, "lng": -104.99 },
        "discountSchedule": [
          { "vendor": "Loves", "discountType": "CENTS_PER_GALLON", "discountAmount": 12 }
        ]
      }
    }
  }'

Required arguments: truck.tankCapacityGallons, truck.mpgForPlanning, currentFuelGallons, origin and destination (each coordinates or a place string like "Denver, CO"). Optional: currentLocation (the truck's live position for a mid-trip replan; defaults to origin), tripId (see replanning below), your discountSchedule (applied on net price), taxRates overrides, and options such as remainingDriveHours (HOS) or weightSensitive planning.

4. Read the plan

The result carries the plan both as readable JSON text and as structuredContent: recommendedStop, plannedStops (with gallonsToPurchase per stop), alternateStops, recommendedGallons, estimatedSavings, a plain-language explanation, and a tripId. Prices per stop include retail, net after your discounts, and IFTA tax-adjusted.

Replanning: call again with the returned tripId, the truck's updated currentLocation, and currentFuelGallons — the engine re-plans the remaining route to the same destination and bills the $0.08 replan rate instead of a new $2.25 plan. Replans stay open for 14 days per trip; a different destination is a new trip (omit the tripId).

Limits and errors

• Rate limit: 30 calls per minute per key.
• card_required — add a payment card on the dashboard to activate the account (nothing is charged).
• credits_exhausted — the balance cannot cover the call; buy credit on the dashboard.
• invalid_trip_id — the tripId is unknown, expired (14 days), or for a different destination. Omit it to start a new plan. Not charged.
• rate_limited — slow down and retry after the indicated delay.
• invalid_request — the arguments failed validation; the message lists the fields. Not charged.
• no_route / no_priceable_stops — the leg could not be routed or no priced station exists on the corridor. Not charged.
• HTTP 401 — missing, invalid, or revoked key.

Fair use

The developer channel is for building agents and apps that plan fuel for trucks. Bulk-harvesting the price grid is not a supported use and gets an account suspended. Building fuel optimization into a commercial product at volume? Talk to us about the partner program.