Quickstart¶

The server speaks MCP Streamable HTTP at:

https://mcp.foliox.ai/mcp

Any MCP-capable client can connect. Pick your path below.

claude.ai / Claude Desktop¶

Open Settings → Connectors → Add custom connector.
Paste https://mcp.foliox.ai/mcp and save.
Click Connect — you'll be sent through your FolioX login. When prompted, pick your organization.
Start a conversation: "What loads do we have today?"

First prompt to try

"Create a 5,000 gallon 87E10 load from Burnaby Refinery to Canco 131 Clement for tomorrow 8am–12pm, lowest free priority slot — validate it and show me before publishing."

Claude Code¶

claude mcp add --transport http foliox https://mcp.foliox.ai/mcp

Then authenticate when prompted (/mcp shows connection status).

Cursor / other MCP clients¶

Add a remote MCP server with URL https://mcp.foliox.ai/mcp. Clients that support OAuth will walk you through the FolioX login; headless clients should use an API key instead.

Headless / server-to-server¶

Send your FolioX customer API key as a standard bearer token — no browser required:

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    "https://mcp.foliox.ai/mcp",
    headers={"Authorization": "Bearer <your-foliox-api-key>"},
)
async with Client(transport) as client:
    tools = await client.list_tools()
    loads = await client.call_tool("find_loads", {"limit": 10})

Or with raw HTTP:

curl -s https://mcp.foliox.ai/mcp \
  -H "Authorization: Bearer <your-foliox-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18",
        "capabilities":{},
        "clientInfo":{"name":"curl","version":"0"}}}'

One credential per request

Send either an OAuth session or an API key — never both. Requests carrying both an Authorization bearer and an X-API-Key header are rejected with AUTH_AMBIGUOUS. See Authentication.

The golden path¶

Whatever the client, the load-building flow is always:

get_build_context (names → ids + live context)
        ↓
validate_load     (dry run — errors[], warnings[], validation_token)
        ↓
create_load       (token + human confirmation → published load)

Everything an agent needs — tank levels, product catalog, terminal allocations, driver availability, taken priority slots, suggested windows — comes back from one get_build_context call.