Skip to main content
Use your deployed backend API origin, or http://127.0.0.1:8090 locally. All /v1/* routes require Authorization: Bearer <service credential or Clerk session JWT>. The API derives tenant, subject, and capabilities from the credential and server mappings.

​
Core routes

Use the indexed catalog and paginated history for discovery rather than repeatedly fetching the entire workspace. Partner routes under /v1/portal use counterparty-scoped credentials; signed /webhooks/edi/{local_tenant} callbacks have their own authentication contract.

​
Roles and writes

Staff roles are viewer, operations, finance, integration, and admin. They can inspect their tenant workspace, including financial evidence, but their write capabilities differ. Carrier/customer portal roles cannot read staff workspace routes. Mutations normally require an Idempotency-Key of 1–200 characters. Preserve the exact key, operation, entity, body, tenant, and actor before dispatch. A matching replay returns the original result; changing the logical request under the key returns 409. Mutation responses use {data, replayed}; workspace reads return the workspace directly. The save resolver instead identifies the original key in its request_key body field. Include the endpoint’s actual expected versions and source evidence. USD amounts are integer cents. A 401 means invalid authentication, 403 missing capability, 404 a missing entity, 409 a conflict, and 422 invalid domain input. Readiness, provider, or admission failures can return 503; a failed write response does not establish whether a transaction committed.

​
Recover an interrupted save

Keep the original request while its outcome is uncertain. Replay only the exact original through its documented endpoint, or use /v1/save-recovery/resolve where the original path is supported. The resolver uses the same tenant transaction lock:
  • If the original committed, return its original completed result.
  • Otherwise, retain a durable stop that prevents delayed copies of that request from applying.
Resolution requires saves.recover and the original route’s capability. It neither reverses completed business work nor applies the original action. The supported set includes root workspace load, invoice, master-data, import, native shipment tracking, and queue-retry saves; it does not cover every API operation. Retain the original key/body while resolution itself is uncertain. After a confirmed outcome, refresh current data; a failed refresh calls for a read retry, not a replacement mutation.

​
Connect the stdio MCP adapter

From the Freight repository, install the adapter dependencies:
Configure your MCP host to launch Node.js 22+ and the repository’s entry point. Replace paths with actual absolute paths; the credential file contains an existing API credential:
Set exactly one of FREIGHT_MCP_TOKEN_FILE or FREIGHT_MCP_TOKEN. The adapter rereads the credential file for each request. Use HTTPS outside loopback. This is a repository build; the reviewed MCP package is private and the setup does not assume a published npm command. For Clerk credentials, additionally set FREIGHT_MCP_IDENTITY_MODE=clerk and the fixed FREIGHT_MCP_ORGANIZATION_ID. Supply a current signed session JWT through the credential source; changing organization requires updating the binding and restarting the adapter. Start with freight_catalog, then use the discovered access and load-catalog reads to verify the intended workspace. Guides under freight://guides/<name> are documentation resources, not live business records. Results preserve request metadata and original response bytes/digests. An interrupted write after dispatch is unconfirmed; a local rejection before dispatch is not_sent. The adapter never automatically retries a write and has no durable command journal of its own. Persist the original tool arguments in the host before calling it. Use resolve_save only for a supported original request.

​
Source contract

This core reference was checked October 20, 2026 against stateset-freight/src/api.rs, src/auth.rs, docs/api.md, docs/save-resolution.md, and mcp/client-config.example.json. Use the repository’s complete request guides and MCP operation catalog for endpoint-specific bodies and evidence requirements. These source contracts do not establish a public hosted URL. Next, verify Freight access and loads or connect Warehouse and Sync.
Last modified on October 20, 2026