Available MCP Tools

This page lists every tool the Alvys MCP server exposes to AI agents. Each tool maps 1:1 to an Alvys Public API capability and requires a specific permission (scope). Your token must carry that scope for the call to succeed. Tool tiers

Read — retrieve data. Always available.
Write — create or update data. Disabled during beta.

Scopes use the {resource}:{action} convention and match the Public API scope catalog. Assign them to your application in Admin → API Access.

During beta, the server is read-only. Write tools (marked below) are disabled.

Conventions

The MCP tool surface mirrors the Public API request/response shapes so calls port 1:1 between the two. Paging. All search tools accept page (0-based, default 0) and pageSize (default 25, max 100). Responses echo the request page back so agents can drive their own pager. page=-1 (or any negative value) is rejected with [invalid_params].

Breaking (2026-07-23): paging is now 0-based, matching the Public API. Callers that previously sent page=1 to get the first page must now send page=0. See the changelog.

Array filters. Filters that map to /search array fields on the Public API (statuses, status, loadNumbers, orderNumbers, mcNumbers, dotNumbers, tripNumbers, driverIds, and so on) are declared as arrays on the tool. Pass one or many values in a single call. Date ranges. Date-range filters are objects: { start, end } in ISO-8601 (e.g. { "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" }). The parameter names match the Public API — createdDateRange, pickupDateRange, deliveryDateRange, invoicedDateRange, paidDateRange, transactionRange. Legacy split-string parameters (createdFrom / createdTo, pickupFrom / pickupTo, etc.) are no longer accepted. Strict arguments. Unknown keys — misspellings, unsupported filters, or parameters that no longer exist — are rejected with [invalid_params]. The error message names the rejected keys and the valid parameter list so an agent can self-correct in one round trip. Nested keys inside a date range or array element are validated too. Missing required arguments and wrong-type values (for example page: "not-an-int") also return structured [invalid_params] errors naming the parameter — for both tools and prompts.

Why: previously, the MCP SDK bound arguments by name and silently discarded unknown ones. customers_search name="Colortech" returned the full unfiltered customer list because name isn’t a valid filter on that tool. That silent-drop behavior is gone — you now get an actionable error instead of a confidently-wrong result.

Tool annotations. Each tool advertises MCP annotations safety hints that mirror the Read / Write / Destructive tiers on this page: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Your MCP client can use these hints to decide whether to ask a human before running a tool. During beta, every exposed tool is read-only and sets readOnlyHint: true (and destructiveHint: false). Example rejection:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "[invalid_params] Unknown parameter(s) for customers_search: 'name'. Valid parameters: createdDateRange, page, pageSize, statuses. Unknown parameters are rejected instead of silently ignored so a misspelled filter cannot return unfiltered results."
    }
  ]
}

Loads

Tool	Tier	Scope	Description
`loads_search`	Read	`load:read`	Search loads by `status`, `loadNumbers`, `orderNumbers`, and/or `customerId`. Provide at least one filter.
`loads_get_by_id`	Read	`load:read`	Fetch a single load including stops, charges, and assignment.

Trips

Tool	Tier	Scope	Description
`trips_search`	Read	`trip:read`	Search trips by `status`, `loadNumbers`, `tripNumbers`, `pickupDateRange`, and/or `deliveryDateRange`. Provide at least one filter; a date range alone is sufficient.
`trips_get_by_id`	Read	`trip:read`	Fetch a single trip including its ordered stops.
`trips_record_arrival`	Write	`stop:update`	Record an arrival event on a trip stop.
`trips_record_departure`	Write	`stop:update`	Record a departure event on a trip stop. Server enforces that an arrival must exist first.
`trips_update_stop_appointment`	Write	`stop:update`	Update the appointment (or FCFS window) on a trip stop. `scheduleType` must be `APPT` or `FCFS`; `appointmentDate` is required for `APPT`, `windowBegin` for `FCFS`.
`trips_assign`	Write	`trip:update`	Assign a carrier, and optionally drivers and equipment, to a trip. Resolve ids first through the search tools. Assigns without dispatching, and recalculates mileage and rate. `driver1Id` is required when `driver2Id` is provided.

Drivers

Tool	Tier	Scope	Description
`drivers_search`	Read	`driver:read`	Search drivers by `name` and/or ELD duty `status` (array). Provide at least one filter. Duty states are ELD telemetry, not dispatch availability.
`drivers_get_by_id`	Read	`driver:read`	Fetch a single driver record.
`drivers_events_search`	Read	`driver:read`	Fetch ELD / duty event history over a date range for one or more drivers (`driverIds` array). Returns raw events, not an Hours-of-Service verdict.

Carriers

Tool	Tier	Scope	Description
`carriers_search`	Read	`carrier:read`	Search carriers by `status`, `mcNumbers`, and/or `dotNumbers`. Provide at least one filter.
`carriers_get_by_id`	Read	`carrier:read`	Fetch a single carrier including insurance and authority data.
`carriers_documents_get`	Read	`carrier:read`	List documents on file for a carrier.
`carriers_set_status`	Write	`carrier:update`	Change a carrier’s status (e.g. activate after onboarding).
`carriers_document_upload`	Write	`carrier:update`	Upload a carrier onboarding document. Send the file as base64; the decoded file must be 5 MB or less.

Customers

Tool	Tier	Scope	Description
`customers_search`	Read	`customer:read`	Search customers by `statuses` (array; defaults to Active, Inactive, Disabled) and/or `createdDateRange`. Results are ordered oldest-first by record-creation date. There is no `name` filter — page and match client-side.
`customers_get_by_id`	Read	`customer:read`	Fetch a single customer including contacts and billing address.
`customers_create`	Write	`customer:create`	Create a new customer.

Trucks & Trailers

Tool	Tier	Scope	Description
`trucks_search`	Read	`truck:read`	Search trucks (power units) by `truckNumber` and/or `status` (array). Provide at least one filter.
`trucks_get_by_id`	Read	`truck:read`	Fetch a single truck by id.
`trucks_events_search`	Read	`truck:read`	Fetch truck events (maintenance, schedule, availability) for one or more trucks over a date range. Pass `truckIds` (array of Alvys truck ids, not unit numbers) and a `startDate`; `endDate` is optional. Returns a flat event list — an empty list means no events in the range.
`trailers_search`	Read	`trailer:read`	Search trailers by `trailerNumber` and/or `status` (array). Provide at least one filter.
`trailers_get_by_id`	Read	`trailer:read`	Fetch a single trailer by id.

Invoices, Fuel & Payments

Tool	Tier	Scope	Description
`invoices_search`	Read	`invoice:read`	Search invoices by `customerId`, `status`, `loadNumbers`, and/or `orderNumbers`, optionally narrowed by `invoicedDateRange` / `paidDateRange`. Provide at least one non-date filter — date ranges narrow results but do not count on their own. `invoicedDateRange` filters on invoice-record creation date (includes `Draft`), so pair it with a status filter for billed-amount questions.
`invoices_get_by_id`	Read	`invoice:read`	Fetch a single invoice including line items.
`fuel_transactions_search`	Read	`fuel:read`	Query fuel transactions by `truckNumber` and/or `transactionRange`. Provide at least one filter.
`invoices_record_carrier_payment`	Write	`invoice:update`	Record a payment to a carrier against a trip. Idempotent on `referenceNumber`. When payments fully cover the carrier payable, the trip transitions to `Completed`.
`invoices_record_customer_payment`	Write	`invoice:update`	Record a payment received from a customer against a load. Idempotent on `referenceNumber`.
`invoices_record_financing`	Write	`invoice:update`	Record a factoring / financing transaction against a load. Idempotent on `referenceNumber`.

Accessorials & Credits

Accessorials are extra charges raised on a load or trip. Credits reduce what is owed. Both use the same reference data: call accessorials_list_types first to get the typeId, the rateType ids that type allows, and the rateUom ids valid for each of those rate types.

Tool	Tier	Scope	Description
`accessorials_list_types`	Read	`accessorial:read`	List the tenant’s accessorial types — the reference data every accessorial create needs. Returns each type’s `Id`, `Name`, whether it `RequiresStop`, and the `RateTypes` it allows with their permitted units of measure. Pass `includeDeleted=true` to also return soft-deleted types, which are reference data only and cannot be charged against.
`accessorials_create_driver`	Write	`accessorial:create`	Create a driver accessorial — an extra amount paid to a driver on a trip (detention, layover, extra stop). `rate` must be greater than zero. Set `applyDriverRate=true` to apply the driver’s configured fee percentage to the rate you pass.
`accessorials_create_customer`	Write	`accessorial:create`	Create a customer accessorial — an extra amount billed to the customer on a load. `rate` must be greater than zero.
`accessorials_create_carrier`	Write	`accessorial:create`	Create a carrier accessorial — an extra amount paid to a carrier on a brokerage trip. `rate` must be greater than zero.
`credits_create_customer`	Write	`accessorial:create`	Post a customer accessorial credit, reducing what the customer owes on a load. `rate` must be a negative value.
`credits_create_carrier`	Write	`accessorial:create`	Post a carrier accessorial credit on a brokerage trip, reducing what the carrier is owed. `rate` must be a negative value.

There is no driver credit tool. A driver credit is a different object from an accessorial — a settlement record rather than a charge on a trip — and is created through the Public API with Create driver credit, which uses the deduction:create scope.

Rate type and unit of measure

rateType and rateUom are sent as ids, and the valid combinations come from accessorials_list_types for the type you are charging.

`rateType`	Meaning	Valid `rateUom` ids
`1`	Flat	`0` only
`2`	Weight	`0` kg, `2` lbs, `4` tons, `5` cwt
`3`	Distance	`0` miles, `1` km
`4`	Volume	`0` gallons, `2` bushels
`5`	Time	`0` minutes, `1` hours, `2` days
`6`	Per Unit	`0` only

quantity must be greater than zero, except with a Flat rateType, which bills the rate once and forces quantity to 1. Pass stopId when the accessorial type returns RequiresStop: true.

Idempotency on accessorial and credit writes

Every create tool accepts an optional externalId — your own key for the record, unique within your tenant. Send the same value on a retry and the original record is returned instead of a second one being created. Omit it and a retry creates a second record.

Keys are case-sensitive and compared after trimming surrounding whitespace.
A retry must ask for the same work: the same rate, quantity, rateType, rateUom, and (for driver accessorials) applyDriverRate, plus the same trip or load, accessorial type, stop, and driver. Reusing a key with any of those changed is refused with 409.
notes is not compared. A retry with a corrected note returns the original unchanged.
A key stays spent after the accessorial is deleted, and cannot be reused across kinds (driver, customer, carrier).

These tools move money. Create only after a human has confirmed the amount. A 503 means the record could not be confirmed, not that it was not created — if you sent an externalId, retry the identical request; if you did not, confirm whether the record exists before retrying.

Visibility & Tracking

Tool	Tier	Scope	Description
`visibility_inbound_history`	Read	`visibility:read`	Fetch inbound tracking events for a load.
`visibility_outbound_history`	Read	`visibility:read`	Fetch outbound tracking events for a load.

Deductions

Tool	Tier	Scope	Description
`deductions_search`	Read	`deduction:read`	Search deductions for a `driverId`, `truckId`, or `ownerOperatorId`. Provide at least one. Pass `includePaid=true` to also return paid deductions (default: open only).
`deductions_get_by_id`	Read	`deduction:read`	Fetch a single deduction by id.

Tenders

Tool	Tier	Scope	Description
`tenders_search`	Read	`tender:read`	Search inbound tenders by `status` (array), `loadNumber`, and/or `shipmentId`.
`tenders_get_by_id`	Read	`tender:read`	Fetch a single inbound tender.
`tenders_create`	Write	`tender:create`	Create (ingest) a new inbound tender. Requires at least two stops.
`tenders_accept`	Write	`tender:update`	Accept an inbound tender, linking each stop to a company. `stopCompanyLinks` must contain at least two entries.
`tenders_accept_updates`	Write	`tender:update`	Accept all pending updates on a tender. Set `applyAllChangesToLoad` to true to apply them to the linked load as well.
`tenders_reject`	Write	`tender:update`	Reject an inbound tender. Provide `reasonCode` and `reasonDescription`; set `cancelLinkedLoad` to true to also cancel the linked load.
`tenders_accept_cancel`	Write	`tender:update`	Accept a tender cancellation.

Error handling

Tool calls return a structured error when they cannot complete. Common cases:

Condition	What it means
`invalid_params`	The call carries an unknown parameter key or an out-of-range value (e.g. `page=-1`). The message names the rejected keys and the tool’s valid parameter list — read it and retry with a corrected argument shape.
Missing scope	Your token does not carry the tool’s required permission. Add the scope in Admin → API Access and re-issue the token.
Write tool disabled	The tool is a write/destructive action disabled during beta.
Rate limited	You exceeded the per-token request limit. Back off and retry.
Response too large	The result exceeded the size cap. Narrow your search filters or paginate.

Model Context Protocol

Overview and connection setup for the Alvys MCP server.

Authentication

Create credentials and issue access tokens with the right scopes.

​Conventions

​Loads

​Trips

​Drivers

​Carriers

​Customers

​Trucks & Trailers

​Invoices, Fuel & Payments

​Accessorials & Credits

​Rate type and unit of measure

​Idempotency on accessorial and credit writes

​Visibility & Tracking

​Deductions

​Tenders

​Error handling

​Related

Model Context Protocol

Authentication

Conventions

Loads

Trips

Drivers

Carriers

Customers

Trucks & Trailers

Invoices, Fuel & Payments

Accessorials & Credits

Rate type and unit of measure

Idempotency on accessorial and credit writes

Visibility & Tracking

Deductions

Tenders

Error handling

Related