> ## Documentation Index > Fetch the complete documentation index at: https://docs.stateset.com/llms.txt > Use this file to discover all available pages before exploring further. # Freight REST API and MCP > TMS credentials, core routes, exact idempotent writes, interrupted-save resolution, and the repository's stdio MCP adapter. Use your deployed backend API origin, or `http://127.0.0.1:8090` locally. All `/v1/*` routes require `Authorization: Bearer `. The API derives tenant, subject, and capabilities from the credential and server mappings. ## Core routes | Method | Route | Purpose | | - | - | - | | GET | `/ready` | Public bounded readiness | | GET | `/v1/access` | Canonical tenant, subject, role, capabilities, and feature flags | | GET | `/v1/loads?limit=25` | Indexed tenant shipment catalog with cursor, search, and filters | | GET | `/v1/workspace` | Staff workspace; complete legacy reads can include substantial history | | GET | `/v1/history` | Paginated original record history | | GET | `/v1/operations` | Source-derived operations queue | | GET | `/v1/console` | Bounded billing/payables/integration queue projection; requires `view` | | POST | `/v1/loads` | Create an explicit transport plan | | GET | `/v1/sync/orders?page=1` | Read configured upstream Sync order candidates; operations permission | | POST | `/v1/sync/import` | Fetch a canonical Sync order and atomically link a planned load | | POST | `/v1/invoices` | Enter/audit a carrier invoice | | POST | `/v1/invoices/{id}/entry-review` | Record named review against invoice evidence | | POST | `/v1/invoices/{id}/approve` | Independent finance approval with business evidence gates | | POST | `/v1/loads/{id}/settlement` | Prepare settlement for an approved invoice | | POST | `/v1/save-recovery/resolve` | Resolve an original supported save as completed or durably stopped | 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: ```bash theme={null} npm --prefix mcp ci ``` 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: ```json theme={null} { "mcpServers": { "stateset-freight": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/stateset-freight/mcp/src/index.mjs"], "env": { "FREIGHT_MCP_API_URL": "http://127.0.0.1:8090", "FREIGHT_MCP_TOKEN_FILE": "/absolute/private/path/freight-token" } } } } ``` 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. | Tool | Contract | | - | - | | `freight_catalog` | Discover registered operation names, methods/paths, and bundled request guides | | `freight_read` | Read a registered GET with an entity ID and literal string query values where applicable | | `freight_write` | Submit a registered operation with original `idempotency_key` and exact `body_json` text | | `freight_upload` | Upload original `body_base64`, content type, key, and required entity/query fields | Start with `freight_catalog`, then use the discovered access and load-catalog reads to verify the intended workspace. Guides under `freight://guides/` 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](/stateset-freight/quickstart#verify-the-data-source) or [connect Warehouse and Sync](/guides/oms-wms-tms). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.