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.
`trips_assign`	Write	`trip:update`	Assign a carrier, driver, and equipment to a trip.

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.
`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).

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.

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. 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.
`invoices_record_financing`	Write	`invoice:update`	Record a factoring / financing transaction.

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.
`tenders_accept`	Write	`tender:update`	Accept an inbound tender, linking each stop to a company.
`tenders_accept_updates`	Write	`tender:update`	Accept all pending updates on a tender.
`tenders_reject`	Write	`tender:update`	Reject an inbound tender.
`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

​Visibility & Tracking

​Deductions

​Tenders

​Error handling

​Related

Model Context Protocol

Authentication

Conventions

Loads

Trips

Drivers

Carriers

Customers

Trucks & Trailers

Invoices, Fuel & Payments

Visibility & Tracking

Deductions

Tenders

Error handling

Related