Flow Engine MCP quickstart

1. Get a key

Sign up with your email, verify it, 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), active immediately; no card is needed until you buy more. Pricing: $2.25 per fuel plan and $0.08 per replan of the same trip; prepaid credit never expires and nothing is ever charged automatically. 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"
      }
    }
  }
}

Claude (connector directory)

Flow is listed in Claude's connector directory. In Claude, open Settings → Connectors → Browse, search ValveRide Flow, and Connect. The listing is at claude.ai/directory.

ChatGPT

In ChatGPT, add Flow as a connector (Settings → Connectors, or a custom GPT's Actions), using the same endpoint https://app.valverideflow.com/api/mcp and your API key. Then just ask ChatGPT for an optimized fuel plan and it calls the Flow engine directly.

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 },
        "vendorRule": { "allowedVendors": ["Loves"] },
        "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), vendorRule.allowedVendors (a strict brand allowlist: only those stations are considered, and an infeasible rule returns no_feasible_plan_under_vendor_rule instead of another brand), 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.
• credits_exhausted — the balance cannot cover the call (free credit spent or expired, no prepaid balance). Buy prepaid credit on the dashboard; nothing is charged automatically.
• 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.