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/mcpEvery 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):
- In Claude, open Customize → Connectors, press + Add and choose Add custom connector.
- Name it ShipEasy, paste
https://app.shipeasyco.com/mcpas its URL and continue. - 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:
- Open Plugins, press Add and choose Add custom MCP server.
- Name it ShipEasy, paste the address as the server URL and leave authentication on OAuth.
- 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#
claude mcp add --transport http shipeasy https://app.shipeasyco.com/mcpThen 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:readquotes:readandquotes:writeshipments:readaddresses: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,httptolocalhost,127.0.0.1or[::1], or Cursor's owncursor://anysphere.cursor-mcplink, 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/authorizesays 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, anotherresource) goes back to the client as?error=, with itsstateandiss(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.1or[::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_grantand 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 withinvalid_grantand ended; send the person through/oauth/authorizeagain. - Calling. The
resourceishttps://app.shipeasyco.com/mcp, and a trailing slash is ignored there and on the URL you call:/mcp/is/mcp. A/mcprequest with no token gets a 401 whoseWWW-Authenticatenames the first document asresource_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_freightandquote_freight_bulk. Each rate gainsbook_url, the web app page where a person books that exact rate. Passinclude_all_carriers: trueto get every carrier's rate for each service, not only the cheapest; each one has its ownbook_url.get_shipment. It gainslinks, 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, andtracking, the public tracking page to share with the receiver (/track/and the shipment'sSHP-reference; the PRO only when it has none). The assistant itself reads the documents withget_shipment_bolandget_shipment_pod.book_quoteandget_booking. They gainlinks: the booking in the web app, and once it is booked its shipment and BOL.next_stepnames tools.track_shipment. It gainslinksto the shipment's web app page and its public tracking page.get_shipment_bolandget_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_idand anidempotency_keyare all it needs; anything still missing is named per field. Booking has every field. preview_bookingtakes the same arguments and answers with exactly what booking would do — stops, day, coverage, card and total — charging nothing. Send itsexpected_amount_usdwithbook_quote, and a total that has moved since is refused rather than charged.get_accountsays beforehand whether this connection can book (booking.ready), and why not, with afix_urlfor 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_methodswhen several are. - The key's booking limits apply: its largest booking amount and its bookings per day.
quote_freightandquote_freight_bulktake a handling unit'shazmatdeclaration, as the endpoints do, andbook_quotebooks such a quote only withhazmat_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_authenticationand carries anauthenticate_url. The assistant should give that link to the person, then pollget_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_freightshows the rates, cheapest first, each with what its service includes, Book and Open in web app.quote_freight_bulkshows 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_bookingshows the booking sheet: both stops, the pickup window, coverage, the total and how it is paid. While coverage is not offered at all (insurance.termsis null), the sheet has no coverage section.book_quoteandget_bookingshow the receipt. It follows the booking until the carrier confirms, then offers the BOL and tracking.track_shipmentshows where the shipment is, in four steps, with the carrier's dates. It has no map and no street address.list_quotesandget_quoteshow 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_shipmentsshows each shipment's PRO, status, lane and dates, with Details.get_shipmentshows its progress, both stops, the freight, the total, its documents, Check status (refresh_shipment_status) and Updates (list_shipment_events).list_scheduleshows 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_eventsandlist_eventsshow a timeline in the web app's words;refresh_shipment_statusandrequest_cancellationshow their answer with a way to the shipment.get_accountshows whether the connection can book, each blocker with a Fix this link, how a booking is paid and today's usage.list_payment_methodsshows 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_catalogandget_catalog_itemshow each model with the boxes it ships in (sizes, weight, units per box) and its total weight.import_catalog,import_package_sizesandimport_originsshow what was added, updated or removed, and each line that could not be taken with the reason; adry_runpreview 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_shipmentswith 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_quotethe exact amount it showed asexpected_amount_usd, so the booking can't charge more than the person saw. A sheet opened from the assistant's ownpreview_bookingbooks what was previewed: its reference and instructions fill the sheet, and itspayment,hazmat_certifiedand 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.comorchat.openai.comis 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_accountlists no API-booking preconditions for a ChatGPT connection:booking.readyis false with oneinsufficient_scopeentry saying where booking happens, and itsfix_urlopens 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 inOPENAI_APPS_CHALLENGEand 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
/mcpcounts as one request. - Each
quote_freightthat 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_bulkcounts 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,
/mcpanswers503 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
InvalidParamserror.