FAQ¶
General¶
Which AI assistants work with this? Anything that speaks MCP over Streamable HTTP: claude.ai, Claude Desktop, Claude Code, Cursor, and any agent built on an MCP client SDK. Headless clients authenticate with an API key instead of OAuth.
Does the agent see all our data? It sees exactly what the connected user (or API key) can see — the backend applies the same tenant scoping and role checks as the FolioX app. Nothing is cached or stored on the MCP server.
Can an agent do something my role can't? No. The MCP server forwards your credential on every call; the backend authorizes each one. An agent connected as a Dispatcher has Dispatcher permissions, nothing more.
Dispatch behavior¶
Why does the agent validate before creating?
validate_load runs the full create-path validation as a dry run and returns
every error and warning at once. It's how agents converge in one step instead
of failing create repeatedly — and it's what makes the create gate possible.
What's a priority slot?
The AM/PM board position for a driver, unique per driver per day.
get_build_context returns each driver's taken_priority_slots for the
requested day — agents pick the lowest free slot. Slots are per-day: context
for today says nothing about tomorrow's board.
Why did cancelling not delete the load? Dispatch never hard-deletes. Cancelled loads keep their history and timeline — that's the audit trail working as intended.
Why did reassignment change the load's id? Reassignment creates a new assignment (same reference code, line items duplicated) and retires the old one. The reference code is the stable handle; the id changes by design.
The agent says a load "can't transition" — why? Loads move through a state machine (assigned → in progress → completed, …). An illegal move returns the load's currently allowed transitions; some moves (driver acceptance, trip progress) belong to the driver/carrier flows, not the dispatcher.
Connection issues¶
The connector connects but tools say the token is "missing the customer claim". Your login isn't carrying an organization. Make sure you pick your organization at login; if you're never prompted, your account needs to be added to one — contact your FolioX administrator.
My API key gets 401.
Check the key is active (FolioX app → API keys), that you're sending it as
Authorization: Bearer <key>, and that your key's IP allowlist (if set)
includes the caller. Also make sure you're not sending an X-API-Key header
and a bearer — that's rejected as ambiguous.
Do mutations (cancel / reassign / edit) work with an API key?
Yes — with a key holding write:loads. The audit history attributes machine
actions to the key itself (actor type api_key + key prefix), so the
timeline always shows who acted.
Data questions¶
How fresh is tank inventory?
query_inventory and get_build_context read the latest telemetry reading
per tank (typically minutes old, up to a week for tanks with sparse
reporting). Each row carries its last_updated_at.
Why does a site show no recommendation?
get_recommended_loads only proposes loads for tanks whose forecasted runout
warrants one — a healthy site is legitimately absent from the list.