FreightCake Docs

Connect AI clients to FreightCake with OAuth and explicitly confirmed shipment actions.

FreightCake's Model Context Protocol (MCP) server lets compatible AI clients work with your organization's quotes, freight shipments, tracking, invoices, carriers, and address book.

Availability

MCP is an opt-in preview. The endpoint is available only in environments where FreightCake has enabled it. Contact FreightCake if your endpoint returns 404. Directory listings and anonymous quoting are not part of this preview.

The hosted endpoint uses Streamable HTTP:

Environment	Endpoint
Production, when enabled	`https://api.freightcake.com/mcp`
Development, when enabled	`https://api.dev.freightcake.com/mcp`

You do not need a local server, database, or a copied API key.

Connect an AI client

Add the endpoint as a remote HTTP MCP server, then complete FreightCake sign-in and review the authorization request. Use a client that supports OAuth authorization-code flow with PKCE.

For example, a VS Code MCP configuration can use:

{
  "servers": {
    "freightcake": {
      "type": "http",
      "url": "https://api.freightcake.com/mcp"
    }
  }
}

FreightCake's authorization and protected-resource metadata allow compatible clients to discover the sign-in endpoints. Do not paste session cookies, API keys, or carrier credentials into a prompt.

An organization administrator must approve the connection. Each connection is bound to that administrator, organization, requested permissions, and selected test/live mode. A connection cannot select another organization by supplying tool arguments.

Permissions

mcp:read: read the connected organization's supported resources.
mcp:write: request quotes and prepare or execute confirmed freight shipment actions. Write access also requires read access.

Grant only the permissions your client needs. Changing account access or revoking the connection invalidates its authorization. Authentication does not bypass account eligibility, payment requirements, shipment state rules, or FreightCake operational controls.

Preview access tokens expire after 15 minutes. Refresh tokens are not issued; your client must reauthorize when its token expires.

Available tools

Tools	Purpose
`list_quotes`, `get_quote`	Read existing quotes
`list_shipments`, `get_shipment`	Read freight shipments
`get_tracking`	Read the latest known tracking for a freight shipment
`list_invoices`, `get_invoice`	Read invoices; does not pay them
`list_carriers`, `get_carrier`	Read supported carriers
`list_addresses`, `get_address`	Read your organization's address book
`request_quotes`	Request and save carrier rate estimates without booking
`prepare_shipment_booking`	Prepare an exact shipment request for your review
`prepare_shipment_cancellation`	Prepare an exact cancellation for your review
`execute_confirmed_action`	Execute an action you approved in FreightCake

List tools return one page at a time. Supply limit (maximum 100) and supported cursor parameters to continue through results. Carrier identifiers are strings; other resource identifiers are positive integers.

This preview focuses on the existing public LTL freight surface. It does not purchase parcel labels, move money, change carrier credentials, expose admin operations, register webhooks, or reset sandbox data.

Booking and cancellation require your approval

Giving a connection write access does not authorize it to book or cancel shipments autonomously.

Ask your client to prepare the booking or cancellation.
The tool returns the exact request, a quote or shipment preview, selected mode, expiration time, and a FreightCake confirmation URL.
Open that URL yourself while signed in as the administrator who connected the client.
Review the details and choose Approve this action or Deny.
Return to your client. It calls execute_confirmed_action using the action ID.

An AI response such as “the user confirmed” is not approval. The client cannot use its OAuth access token to impersonate your browser session or approve the action. Approval is bound to the exact stored request; the client cannot change its arguments afterward.

Confirmations expire after ten minutes. A changed quote price requires a new request and confirmation. Repeating a completed action returns its recorded result instead of creating another shipment.

Understand the shipment result

Freight quote prices are estimates, expressed in cents, not dollars. Carrier reweigh, reclassification, and other adjustments can change the final charge.
Creating freight may issue a BOL or create a prepaid draft that still needs payment in FreightCake. Inspect the returned bol_status, shipment_status, and any payment instructions.
Creating freight does not schedule carrier pickup. Complete pickup and any remaining release requirements in FreightCake.
Cancellation is subject to the existing shipment-state rules. Do not assume a carrier pickup was cancelled merely because a local document was voided.

Errors and retries

Resource failures are returned as MCP tool errors with the underlying public API error details. The server does not turn a rejected booking into a success.

If an execution has an uncertain outcome, inspect your shipments in FreightCake before doing anything else. Do not prepare another booking simply because the client timed out. FreightCake prevents concurrent execution of the same action, but a carrier can accept a request before a response is lost.

Rate limits apply to MCP requests and underlying resource operations. Operational freezes can disable writes while leaving read tools available.

MCP Server