Skip to content

AI agents (MCP)

Contents 26 pages

Connect your own AI assistant to ShipEasy. It can rate freight, find your shipments and follow them, read their documents, and, when you allow it to, book, cancel and keep your address book. It follows the same rules as the REST API.

ShipEasy speaks the Model Context Protocol at one URL:

https://app.shipeasyco.com/mcp

Every organization can use it, unless ShipEasy has switched its API access off. A Shopify store connects through its Shopify app instead ("Connect your store instead" when ShipEasy asks you to sign in, or on the page that asks what the app may do), and sees its shipments place-only: see Shopify stores. Whether an assistant may also book, cancel or edit is yours to decide, connection by connection and key by key, and only an owner or admin can allow it. During an incident ShipEasy can switch off, for everyone, every tool that changes something: assistants then only read and quote.

Connect#

Add ShipEasy to your AI app#

AI apps sign in to ShipEasy instead of taking a key, so there is nothing to copy but the address. The same steps, one tab per app, are on AI & API in the web app's menu (/portal/ai), and for a Shopify store on AI & API in its app's menu.

Claude (on the web, desktop and phone):

  1. In Claude, open Customize → Connectors, press + Add and choose Add custom connector.
  2. Name it ShipEasy, paste https://app.shipeasyco.com/mcp as its URL and continue.
  3. Press Connect. Claude sends you to ShipEasy: sign in as an owner or admin, and choose what it may do. Allow takes you back to Claude.

ChatGPT:

  1. Open Plugins, press Add and choose Add custom MCP server.
  2. Name it ShipEasy, paste the address as the server URL and leave authentication on OAuth.
  3. Tick I understand and want to continue, create it, then sign in to ShipEasy and press Allow. ChatGPT may quote and track; it never books (see ChatGPT).

Cursor and VS Code: press Add to Cursor or Add to VS Code on AI & API, or add the server by hand: in Cursor, a server named shipeasy whose url is the address; in VS Code, MCP: Add Server from the Command Palette, then HTTP and the address. Each asks you to sign in to ShipEasy the first time it connects.

Any other app that can add a remote MCP server (some call it a custom connector or custom app) works the same way: give it the address, and it sends you to ShipEasy to sign in.

On the ShipEasy page:

  • It names the organization. If you are an owner or admin of more than one, choose which.
  • Choose what the app may do (see what an AI app may do).
  • It names the address the app will send you back to, and warns when it is not one ShipEasy knows.
  • Unless you signed in within the last few minutes, confirm it's you: type your password, or sign in again with Google or a passkey, which brings you back to the same page with the organization and choice you picked still selected, and then press Allow. If Google takes more than 10 minutes, you come back to the same page too, told to try again, with your choice kept, and the AI app is still waiting.
  • If it can't connect, it says why: a member is told which owner to ask, and an organization ShipEasy switched off is named. Without two-factor sign-in it offers Set up two-factor, which comes back to the page when done.

What an AI app may do#

While ShipEasy's newer areas are on for your account, the page asks area by area. Quote and track is always included: it reads your account, rates freight, and follows quotes and shipments, and it also reads your saved addresses, catalog, support cases, settings, documents and analytics. Then a box for each area it may also do, none ticked at first, with Select all:

Area It may also Scopes
Book shipments Book a rate, on a card it may list. This spends money. bookings:read bookings:write
Refresh and cancel shipments Ask a carrier for news, and cancel a shipment. shipments:write
Address book and saved shipments Add, edit and remove origins, consignees and templates. addresses:write
Catalog Add, edit, remove and import models (a store's package sizes). catalog:write
Support cases and requests Open and answer cases, send feedback, ask for White Glove. support:write
Settings and branding Change defaults, notifications, text alerts, logo and reply-to email. settings:write
Team Invite, change and remove members, never the owner. team:read team:write
API keys and webhooks Make and revoke keys, add and remove endpoints, disconnect other AI apps. developers:read developers:write
Cards and invoices Read invoices and payments; links to pay or add a card; rename or remove one. payments:read payments:write

Booking never reads invoices or payments: those are Cards and invoices alone. A Shopify store is offered its own: no address book, team, or cards and invoices (those live in Shopify), Saved shipments instead of the address book, and Billing, which reads what ShipEasy charged the store (payments:read). ChatGPT is never offered booking or cards and invoices. While ShipEasy has the tools that change something switched off, no area that changes anything is offered (a store's Billing, which only reads, still is), and changing a connection's areas meanwhile keeps the ones it holds but cannot be offered. The server refuses any area it did not offer.

Until those areas are on, the page offers three levels instead: Quote and track (the default), Quote, track and book, or Quote, track, book and manage.

Change it later without connecting again: on AI & API, an owner or admin flips the area's switch on the connection's card, which saves at once (a store ticks the same areas in its ShipEasy app). The change applies to the app's next request. get_account says what the connection may do in connection.areas, what it could also do in connection.missing_areas, and where to change it in connection.change_url. A connection without Book shipments sees one insufficient_scope entry in booking.blockers saying to tick it there, with fix_url on that page (until areas are on, it says to reconnect and choose Quote, track and book).

Claude Code#

Shell
claude mcp add --transport http shipeasy https://app.shipeasyco.com/mcp

Then type /mcp in a Claude Code session and choose ShipEasy to sign in, the same way as above. No key is needed.

With an API key#

Any other MCP client, a script, or the Claude API connects with an API key from /portal/api-keys. The agent sees only the tools that key's scopes reach, so give it what it needs and no more. For an assistant that quotes and tracks, press For an AI agent (MCP) above the scopes when you create the key (it shows while MCP is on), or tick:

  • account:read
  • quotes:read and quotes:write
  • shipments:read
  • addresses:read

To let it book, press For an AI agent that books instead, or also tick bookings:write and bookings:read. Only an owner or admin can, and the key's booking limits apply (see Booking). Add shipments:write for cancelling and refreshing tracking, and addresses:write for editing saved addresses.

Any MCP client. Use the Streamable HTTP transport, and send the key as Authorization: Bearer se_live_… on every request. The server keeps no session: each POST carries one JSON-RPC message and gets one JSON answer. It speaks MCP 2026-07-28 to a client that opens with server/discover, and 2025-11-25 (or an earlier 2025 version) to one that opens with initialize. In Claude Code, add --header "Authorization: Bearer se_live_…" to the command above.

The Claude API's MCP connector. Pass the same URL, with the key as the server's authorization_token.

The connection#

The app then holds a connection, not a key you can see. Its access token lasts an hour and the app renews it by itself; a connection not renewed for 90 days ends. The token works only at /mcp, and the REST API refuses it. Every renewal checks that the person who connected it is still an owner or admin and that the organization's API access is on.

The connection is listed on /portal/ai under Connected AI apps, with who connected it and what it may do. Disconnect ends it at once, and so does removing the connector in the app.

A connection belongs to the person who allowed it as well as to the organization, so it also ends at once whenever every one of that person's sessions does: when they Sign out everywhere, change or reset their password, change their sign-in email, lock password checks with wrong guesses, or delete their account, and when ShipEasy disables or deletes the account, resets its two-factor or sets it a temporary password. Each one is disconnected the way Disconnect does it, in every organization the person connected it to. When the person leaves an organization, or is removed from it, only the connections to that organization end. A renewal also refuses any connection allowed before the person's latest such cutoff. The organization's ordinary API keys are not touched. Connect the app again afterwards.

For client authors: the server publishes /.well-known/oauth-protected-resource (RFC 9728), also at its path-suffixed address /.well-known/oauth-protected-resource/mcp, and /.well-known/oauth-authorization-server (RFC 8414). It offers dynamic client registration (RFC 7591), the authorization code flow with PKCE S256 only, refresh tokens that rotate on every use, and revocation (RFC 7009).

  • Registering. Up to 10 redirect URIs, each https, http to localhost, 127.0.0.1 or [::1], or Cursor's own cursor://anysphere.cursor-mcp link, with no fragment. One address may register 20 clients an hour. A client nothing has used for 30 days, and that holds no live connection, is deleted; register again when /oauth/authorize says the connector isn't registered.
  • Authorizing. A code must be traded within 5 minutes. A request with a problem in it (another response_type, no PKCE, another resource) goes back to the client as ?error=, with its state and iss (RFC 9207), only when it returns to Cursor's own link or the redirect's host is one ShipEasy knows: claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, localhost, 127.0.0.1 or [::1]. For any other host the person sees the problem and is sent nowhere, so a registered client cannot use ShipEasy to send people to another site. An unknown client, or a redirect it never registered, is always shown and never followed.
  • Refreshing. A refresh token used after it was rotated ends the connection, except the one replaced in the last 60 seconds: that request is refused with invalid_grant and the connection stays, so two refreshes sent close together cost you nothing. A connection whose person has signed out everywhere (or had every session ended another way) since allowing it is refused with invalid_grant and ended; send the person through /oauth/authorize again.
  • Calling. The resource is https://app.shipeasyco.com/mcp, and a trailing slash is ignored there and on the URL you call: /mcp/ is /mcp. A /mcp request with no token gets a 401 whose WWW-Authenticate names the first document as resource_metadata.

Tools#

Each tool is one REST endpoint. Its arguments and its answer are that endpoint's own: query parameters and the request body become arguments, path parameters become snake_case arguments (shipment_id), and the Idempotency-Key header becomes an idempotency_key argument.

Tool Endpoint Scope
get_account GET /api/v1/account account:read
quote_freight POST /api/v1/quotes quotes:write
quote_freight_bulk POST /api/v1/quotes/bulk quotes:write
list_quotes GET /api/v1/quotes quotes:read
get_quote GET /api/v1/quotes/{quoteId} quotes:read
preview_booking POST /api/v1/bookings/preview bookings:write
book_quote POST /api/v1/bookings bookings:write
get_booking GET /api/v1/bookings/{chargeId} bookings:read
list_payment_methods GET /api/v1/payment_methods payments:read or bookings:write
list_shipments GET /api/v1/shipments shipments:read
list_schedule GET /api/v1/schedule shipments:read
get_shipment GET /api/v1/shipments/{shipmentId} shipments:read
list_shipment_events GET /api/v1/shipments/{shipmentId}/events shipments:read
list_events GET /api/v1/events shipments:read
get_shipment_bol GET /api/v1/shipments/{shipmentId}/bol shipments:read
get_shipment_pod GET /api/v1/shipments/{shipmentId}/pod shipments:read
get_shipment_label GET /api/v1/shipments/{shipmentId}/label shipments:read
refresh_shipment_status POST /api/v1/shipments/{shipmentId}/refresh-status shipments:write
request_cancellation POST /api/v1/shipments/{shipmentId}/cancel shipments:write
track_shipment GET /api/v1/tracking/{pro} shipments:read
list_orders GET /api/v1/orders (Shopify stores only) shipments:read
get_order GET /api/v1/orders/{orderId} (Shopify stores only) shipments:read
quote_order POST /api/v1/orders/{orderId}/quote (Shopify stores only) quotes:write
list_origins GET /api/v1/origins addresses:read
get_origin GET /api/v1/origins/{originId} addresses:read
save_origin POST /api/v1/origins addresses:write
replace_origin PATCH /api/v1/origins/{originId} addresses:write
delete_origin DELETE /api/v1/origins/{originId} addresses:write
list_destinations GET /api/v1/destinations addresses:read
get_destination GET /api/v1/destinations/{destinationId} addresses:read
save_destination POST /api/v1/destinations addresses:write
replace_destination PATCH /api/v1/destinations/{destinationId} addresses:write
archive_destination DELETE /api/v1/destinations/{destinationId} addresses:write
restore_destination POST /api/v1/destinations/{destinationId}/restore addresses:write
import_origins POST /api/v1/origins/imports addresses:write
list_catalog GET /api/v1/catalog catalog:read
get_catalog_item GET /api/v1/catalog/{modelId} catalog:read
save_catalog_item POST /api/v1/catalog catalog:write
replace_catalog_item PATCH /api/v1/catalog/{modelId} catalog:write
delete_catalog_item DELETE /api/v1/catalog/{modelId} catalog:write
import_catalog POST /api/v1/catalog/imports catalog:write
list_package_sizes GET /api/v1/package_sizes (Shopify stores only) catalog:read
get_package_size GET /api/v1/package_sizes/{packageSizeId} (Shopify stores only) catalog:read
save_package_size POST /api/v1/package_sizes (Shopify stores only) catalog:write
replace_package_size PATCH /api/v1/package_sizes/{packageSizeId} (Shopify stores only) catalog:write
delete_package_size DELETE /api/v1/package_sizes/{packageSizeId} (Shopify stores only) catalog:write
restore_package_size POST /api/v1/package_sizes/{packageSizeId}/restore (Shopify stores only) catalog:write
import_package_sizes POST /api/v1/package_sizes/imports (Shopify stores only) catalog:write
list_templates GET /api/v1/templates quotes:read
get_template GET /api/v1/templates/{templateId} quotes:read
save_template POST /api/v1/templates addresses:write
rename_template PATCH /api/v1/templates/{templateId} addresses:write
delete_template DELETE /api/v1/templates/{templateId} addresses:write
quote_from_template POST /api/v1/templates/{templateId}/quote quotes:write
rate_shipment_again POST /api/v1/shipments/{shipmentId}/ship-again quotes:write
get_status_report GET /api/v1/shipments/report shipments:read
export_shipments GET /api/v1/shipments/export shipments:read
refresh_shipments POST /api/v1/shipments/refresh-status shipments:write
list_calendar_links GET /api/v1/schedule/links shipments:read
create_calendar_link POST /api/v1/schedule/links shipments:write
revoke_calendar_link DELETE /api/v1/schedule/links/{linkId} shipments:write
list_support_cases GET /api/v1/support/cases support:read
get_support_case GET /api/v1/support/cases/{caseId} support:read
open_support_case POST /api/v1/support/cases support:write
reply_support_case POST /api/v1/support/cases/{caseId}/messages support:write
send_feedback POST /api/v1/feedback support:write
request_white_glove POST /api/v1/white_glove_requests support:write
list_notifications GET /api/v1/notifications support:read
mark_notifications_read POST /api/v1/notifications/read support:write
list_documents GET /api/v1/documents documents:read
get_document GET /api/v1/documents/{documentId} documents:read
get_settings GET /api/v1/settings settings:read
update_settings PATCH /api/v1/settings settings:write
set_up_text_alerts POST /api/v1/settings/text_alerts settings:write
confirm_text_alerts POST /api/v1/settings/text_alerts/confirm settings:write
remove_text_alerts DELETE /api/v1/settings/text_alerts settings:write
get_branding GET /api/v1/branding settings:read
update_branding PATCH /api/v1/branding settings:write
set_brand_logo POST /api/v1/branding/logo settings:write
remove_brand_logo DELETE /api/v1/branding/logo settings:write
send_brand_test_email POST /api/v1/branding/test_email settings:write
set_reply_to_email POST /api/v1/branding/reply_to settings:write
remove_reply_to_email DELETE /api/v1/branding/reply_to settings:write
set_tracking_domain POST /api/v1/branding/tracking_domain settings:write
check_tracking_domain POST /api/v1/branding/tracking_domain/check settings:write
remove_tracking_domain DELETE /api/v1/branding/tracking_domain settings:write
get_referrals GET /api/v1/referrals settings:read
list_members GET /api/v1/members team:read
invite_member POST /api/v1/invitations team:write
revoke_invitation DELETE /api/v1/invitations/{invitationId} team:write
update_member PATCH /api/v1/members/{memberId} team:write
remove_member DELETE /api/v1/members/{memberId} team:write
list_api_keys GET /api/v1/api_keys developers:read
create_api_key POST /api/v1/api_keys developers:write
rotate_api_key POST /api/v1/api_keys/{apiKeyId}/rotate developers:write
revoke_api_key DELETE /api/v1/api_keys/{apiKeyId} developers:write
list_webhook_endpoints GET /api/v1/webhook_endpoints developers:read
add_webhook_endpoint POST /api/v1/webhook_endpoints developers:write
update_webhook_endpoint PATCH /api/v1/webhook_endpoints/{endpointId} developers:write
rotate_webhook_secret POST /api/v1/webhook_endpoints/{endpointId}/rotate_secret developers:write
send_webhook_test POST /api/v1/webhook_endpoints/{endpointId}/test_event developers:write
remove_webhook_endpoint DELETE /api/v1/webhook_endpoints/{endpointId} developers:write
list_ai_connections GET /api/v1/ai_connections developers:read
disconnect_ai_connection DELETE /api/v1/ai_connections/{connectionId} developers:write
get_usage GET /api/v1/usage developers:read
list_invoices GET /api/v1/invoices payments:read
get_invoice GET /api/v1/invoices/{invoiceId} payments:read
get_invoice_pdf GET /api/v1/invoices/{invoiceId}/pdf payments:read
pay_invoice POST /api/v1/invoices/{invoiceId}/pay payments:write
list_payments GET /api/v1/payments payments:read
get_card_setup_link GET /api/v1/payment_methods/setup payments:write
update_payment_method PATCH /api/v1/payment_methods/{cardId} payments:write
remove_payment_method DELETE /api/v1/payment_methods/{cardId} payments:write
list_stores GET /api/v1/stores settings:read
import_store_products POST /api/v1/stores/{storeId}/product_imports catalog:write
disconnect_store DELETE /api/v1/stores/{storeId} settings:write
list_store_orders GET /api/v1/store_orders shipments:read
quote_store_orders POST /api/v1/store_orders/quote quotes:write
get_analytics GET /api/v1/analytics analytics:read
export_analytics GET /api/v1/analytics/export analytics:read

GET /api/v1/ping and GET /api/v1/openapi.json have no tool: connecting already proves the key, and each tool carries its own schema.

Every tool says whether it only reads. book_quote, request_cancellation, the replace, delete and archive tools, and save_destination (an address already saved takes what you send) are marked destructive, so a client that honours the marking asks the person before it runs them; book_quote and request_cancellation also ask Claude to confirm with the person on every call. The tools that reach a carrier (quoting, booking, cancelling, refreshing) or a person or system outside ShipEasy (an invitation or test email, a text, a webhook's URL, a calendar feed) are marked as reaching outside ShipEasy. preview_booking only reads, though it takes a booking's body.

The tools' words are the REST reference's, with each endpoint it mentions named as the tool instead (quote_freight, not POST /quotes), and a sentence on what the tool is for and what comes next. The server also hands every client a short playbook: find saved places, quote, preview, ask the person, book, then check the booking.

Prompts#

Three conversation starters, which Claude Code and VS Code show as slash commands and other clients may offer as suggestions:

  • ship_freight — quote a shipment, preview the chosen rate, book it after a yes.
  • track_shipments — shipments booked or in transit, with anything that needs attention.
  • compare_carriers — every carrier's price and transit time on one lane.

A Shopify store is offered ship_order in place of ship_freight: rate one of its unfulfilled orders and book the rate it picks.

While mcpEverything is on, a fourth starter edits what a quote is built from, previewing every change before it is saved: manage_catalog for an organization's catalog, manage_package_sizes for a store's product sizes.

A few answers add a field the REST endpoint doesn't have:

  • quote_freight and quote_freight_bulk. Each rate gains book_url, the web app page where a person books that exact rate. Pass include_all_carriers: true to get every carrier's rate for each service, not only the cheapest; each one has its own book_url.
  • get_shipment. It gains links, every one a page a person can open: the shipment in the web app, its BOL, POD and label through the signed-in web app once they exist, and tracking, the public tracking page to share with the receiver (/track/ and the shipment's SHP- reference; the PRO only when it has none). The assistant itself reads the documents with get_shipment_bol and get_shipment_pod.
  • book_quote and get_booking. They gain links: the booking in the web app, and once it is booked its shipment and BOL. next_step names tools.
  • track_shipment. It gains links to the shipment's web app page and its public tracking page.
  • get_shipment_bol and get_shipment_pod. They answer with the PDF itself, as an embedded resource, so the assistant can read it. A document over 5 MB is refused; download it from the web app instead.

Booking#

book_quote is POST /api/v1/bookings, with every rule that endpoint has:

  • It takes that endpoint's own body. When the quote already holds both stops (a saved origin and destination, or the street sent with the quote), a rate's quote_id and an idempotency_key are all it needs; anything still missing is named per field. Booking has every field.
  • preview_booking takes the same arguments and answers with exactly what booking would do — stops, day, coverage, card and total — charging nothing. Send its expected_amount_usd with book_quote, and a total that has moved since is refused rather than charged.
  • get_account says beforehand whether this connection can book (booking.ready), and why not, with a fix_url for each reason.
  • An invoiced organization books on account. Otherwise it charges the card enabled for API bookings — the only one, or the one named from list_payment_methods when several are.
  • The key's booking limits apply: its largest booking amount and its bookings per day.
  • quote_freight and quote_freight_bulk take a handling unit's hazmat declaration, as the endpoints do, and book_quote books such a quote only with hazmat_certified: true, which the assistant sends once the person has certified the declaration. The rate card's Book sheet sends no certification, so on a declared quote it shows the refusal and Finish in the web app, where the box is. See Hazardous materials.
  • When the card's bank wants the cardholder to approve the charge, the answer says requires_authentication and carries an authenticate_url. The assistant should give that link to the person, then poll get_booking. The link is handed out once.

Cards#

In an AI app that shows MCP Apps (Claude, ChatGPT, Cursor and VS Code), every tool except those that answer with a file answers with a ShipEasy card as well as its text. Claude Code and other text-only apps get the same answers without the card. The file tools answer with the file itself: the PDFs (get_shipment_bol, get_shipment_pod, get_shipment_label, get_document, get_invoice_pdf) and the CSV exports (export_shipments, export_analytics).

  • quote_freight shows the rates, cheapest first, each with what its service includes, Book and Open in web app.
  • quote_freight_bulk shows every lane in the order sent, with its cheapest rate and how many others it has, a lane that could not be rated with the reason, and what the cheapest rates add up to. See rates opens that lane's rate card, which leads back to every lane.
  • preview_booking shows the booking sheet: both stops, the pickup window, coverage, the total and how it is paid. While coverage is not offered at all (insurance.terms is null), the sheet has no coverage section.
  • book_quote and get_booking show the receipt. It follows the booking until the carrier confirms, then offers the BOL and tracking.
  • track_shipment shows where the shipment is, in four steps, with the carrier's dates. It has no map and no street address.
  • list_quotes and get_quote show saved quotes: the lane each was rated for, whether it can still be booked and until when, with Book, or View shipment once booked.
  • list_shipments shows each shipment's PRO, status, lane and dates, with Details. get_shipment shows its progress, both stops, the freight, the total, its documents, Check status (refresh_shipment_status) and Updates (list_shipment_events).
  • list_schedule shows the days asked for as an agenda: each day's pickups and deliveries in the web app calendar's words (Awaiting pickup confirmation, Running late, Preferred delivery day with its not-guaranteed note), the lane, the carrier and the window, with Details opening the shipment.
  • list_shipment_events and list_events show a timeline in the web app's words; refresh_shipment_status and request_cancellation show their answer with a way to the shipment.
  • get_account shows whether the connection can book, each blocker with a Fix this link, how a booking is paid and today's usage. list_payment_methods shows the cards on file and which have API bookings on.
  • The address book tools show saved pickup places and destinations as address labels, and a removal as a short confirmation.
  • list_catalog and get_catalog_item show each model with the boxes it ships in (sizes, weight, units per box) and its total weight. import_catalog, import_package_sizes and import_origins show what was added, updated or removed, and each line that could not be taken with the reason; a dry_run preview says nothing is saved yet.
  • The other areas' tools (saved shipments, support cases, notifications, documents, settings and branding, the team, API keys, webhooks, AI apps, invoices, payments, stores and their orders, analytics) show their records as a list, or one record's facts, with its status as a tag. A pay link or a card setup link is a button that opens the page; nothing is charged from the card. A new API key's or webhook's secret shows once, to copy.
  • A status tag wears the web app's chip colour for that status: a shipment In transit the ink, Delivered green, Needs attention and Cancellation requested amber, Cancelled plain; a calendar line as on the web calendar; a saved quote as on the web app Bot's card, Bookable blue and Booked green.
  • A list longer than the card's first rows has Show more; a list with more pages says so, and the assistant fetches the next one.
  • An empty list says so in its own words. list_shipments with no filter says there are no shipments yet, and with one says none match.

On the cards:

  • A card offers only what its connection may do: each answer tells the card which tools that connection may call. Without booking (any ChatGPT connection), a rate's Book on ShipEasy opens the web app's booking page, and a store's card says to book in its ShipEasy app in Shopify admin; without refreshing tracking, a shipment has no Check status.
  • Book opens the booking sheet. Nothing is charged until the person presses Book for $X on the sheet, and that press is their confirmation. The sheet sends book_quote the exact amount it showed as expected_amount_usd, so the booking can't charge more than the person saw. A sheet opened from the assistant's own preview_booking books what was previewed: its reference and instructions fill the sheet, and its payment, hazmat_certified and requested-delivery fields are sent unchanged. Ticked coverage waits for a value and the terms before Book is offered.
  • An edit on the sheet is previewed before it can be booked. A retry of the same sheet reuses its idempotency_key, so pressing twice books once.
  • After a booking, the card tells the assistant, so it doesn't book that quote again.
  • The receipt checks the booking every 5 seconds for the first 30 seconds, then every 15, at most 20 times. It stops as soon as the booking is final.
  • Every link opens in the person's browser through the AI app. A card loads nothing from anywhere and calls only ShipEasy's own tools.
  • The server's instructions ask the assistant not to repeat a card's rows as a table or list, but to say what matters and the next step in a sentence or two. In an app that shows no cards, it lists them. ChatGPT gets the same ask with the card itself (openai/widgetDescription), which it reads when a card loads.

A Shopify store's connection gets the same cards, in store mode. Book has no sheet, so it shows only once the quote holds both stops' details (missing_for_booking is empty); until then the card asks for them in the chat, and the assistant books with them. It calls book_quote with the rate's price as expected_amount_usd and one idempotency_key per button, and the receipt asks the person to Approve in Shopify, where the charge's total is shown before anything is charged. list_orders and get_order show the store's orders with where each ships and what is in it; Get rates calls quote_order and opens the order's rates. Links open the store's ShipEasy app in Shopify admin, never the web app, and a store's shipment shows regions, not streets.

The tools point at the card page with _meta.ui.resourceUri, a ui://shipeasy/app-<hash>.html resource of type text/html;profile=mcp-app that resources/list and resources/read serve; a store's tools point at ui://shipeasy/store-<hash>.html, the same page in store mode. The hash changes whenever the page does. A URI from an earlier version still reads the current page.

Parity#

An AI app can do what a person can do in the web app or the Shopify app. Every page and action of both apps maps to the operations that do the same, each an MCP tool, or says why it stays out of chat:

  • signing in, a person's own profile and security, and one-time links from an email;
  • the consent page where an AI app is let in;
  • the apps' own ShipEasy Bot (in an AI app, the AI app is the assistant);
  • for a store, anything that would hand over a buyer's name or street (the paperwork, the ship-to book) and Shopify's own permission screens.

tests/unit/architecture/aiParity.test.ts fails a change that adds a page or an action without its AI answer.

ChatGPT#

A connection from ChatGPT quotes and tracks, and never books or pays. OpenAI lets an app in ChatGPT sell only physical goods, with checkout on the seller's own site, so ShipEasy keeps booking and payment on ShipEasy:

  • The sign-in page offers ChatGPT Quote and track only, and refuses any other level, for an organization and for a Shopify store alike. Any connection whose redirect returns to chatgpt.com or chat.openai.com is held to this. Once ShipEasy turns on managing from ChatGPT, it is offered every area except Book shipments, Cards and invoices and a store's Billing.
  • A rate's Book opens the web app's booking page for that quote (a store books in its ShipEasy app in Shopify admin), where the person sees the total and books.
  • get_account lists no API-booking preconditions for a ChatGPT connection: booking.ready is false with one insufficient_scope entry saying where booking happens, and its fix_url opens the web app's quotes (a store's, its Shopify app). The account card shows it as Booking happens on ShipEasy.
  • OpenAI checks that we own the domain by reading /.well-known/openai-apps-challenge, which answers the token set in OPENAI_APPS_CHALLENGE and is a 404 until then.

The package OpenAI reviews (listing, icons, test cases) is versioned in integrations/chatgpt/, with the steps to submit it.

Idempotency#

quote_freight_bulk, book_quote and request_cancellation require an idempotency_key; every other write accepts one. Send a fresh UUID for each new intent, and the same one to retry it. A retry answers with the first outcome instead of doing the work twice, exactly as Idempotency describes for the header. The key is shared with the REST API: the same key on the same endpoint is the same request on either.

Limits, quotas and refusals#

Everything in Rate limits & quotas applies.

  • Each POST to /mcp counts as one request.
  • Each quote_freight that returns rates counts as one quote against your organization's daily budget, which it shares with the web app and the REST API. quote_freight_bulk counts one per lane that rated.

A refusal is a tool result with isError: true, and it is counted against the key or AI app for your owners and admins to see under AI & API → Usage & problems (refusals you can see). Its text is the REST API's own error envelope, with the same code and request_id, so you handle it the way you would the REST call — except that its words name tools rather than endpoints. Where a person can fix the refusal, it carries a fix_url to the web app page that does. While ShipEasy has the tools that change something switched off, every tool but those that read or quote (quote_freight, quote_freight_bulk and the other quoting tools) answers api_unavailable and is not listed. A missing or bad key is refused before any tool runs, with the same 401 the REST API sends.

Some other refusals also come before any tool:

  • With MCP switched off, /mcp answers 503 api_unavailable.
  • A body that is not sent as application/json, is not JSON, is over 1 MiB, or is a JSON-RPC batch gets a JSON-RPC error: HTTP 415 for the content type, 413 for the size, 400 otherwise.
  • An unknown tool name is a JSON-RPC InvalidParams error.