tools/call over POST /webshipper/mcp. The connector is
connected with the account name and an API token from Webshipper (see
Connect Webshipper). Your organization needs
access to Webshipper (a subscription, or a plan that covers it, see
What decides access), and your
user must hold a seat or plan licence (assigned under Team in the portal, see
Team).
Endpoint:
https://mcp.consile.ai/webshipper/mcp. Webshipper is its own named
connector with only its own tools. Each tool is exposed as webshipper__<tool>
(e.g. webshipper__search_orders); the bare names are used here for
readability. A bare name in a request returns Unknown tool.The connector is multi-instance: one connection reaches exactly one Webshipper
account. Each additional account (an agreement, aftale, in the portal) is
served on its own endpoint, e.g. https://mcp.consile.ai/webshipper-2/mcp, with
tools named webshipper-2__<tool>. Agreements are added in the portal by an
administrator.Besides the connector tools, tools/list on every Webshipper endpoint includes
the unprefixed system tool connect_account (no arguments). It returns
{ connect_url, instructions }: a link, valid for 10 minutes, that the user
opens in the browser to connect (or reconnect) that endpoint’s account.tools/list on this endpoint returns the
15 webshipper__* tools plus connect_account. Without access only
connect_account is listed. A user without a seat still sees the tools, but every
call is refused. Read tools are annotated readOnlyHint: true,
destructiveHint: false, openWorldHint: false. Write tools carry
readOnlyHint: false and destructiveHint: true; openWorldHint is true on
create_shipment (it reaches the carrier and can notify the recipient) and
false on the other two; idempotentHint is true on update_order and false
on create_shipment and create_order.
Shared conventions
One account per connection
A Webshipper connection reaches exactly one account: the one named by the account name given when the connection was made (<account>.webshipper.io). Every
request goes to that account’s own API host. No tool takes an account argument,
and no argument can point a request at another host.
Ids
Every Webshipper id (order, shipment, shipping rate, order channel, carrier) is a positive integer within the account. The shop’s own order number is not the order id: it isvisibleRef, which search_orders can filter on. Find ids with
the search and list tools.
Pagination
search_orders, search_shipments and search_returns are paged by Webshipper’s
fixed 30 records per page:
nextPage, and a shorter page omits it. The last page can therefore be empty.
The setup lists (list_shipping_rates, list_carriers, list_order_channels)
are not paged. They read every page up to a cap and return truncated: true when
records were left out.
Dates and countries
- Dates are
YYYY-MM-DD.createdFromandcreatedTofilter on the record’s creation time and are both inclusive.createdFrommust not be aftercreatedTo. - Countries are ISO 3166-1 alpha-2 codes (
DK,SE,NO). Currencies are ISO 4217 codes (DKK,EUR). - Weights take a
weightUnitofgorkg.
Data minimisation
- Order channels and carriers hold the shop’s access tokens and the carrier agreements’ credentials. Those are never returned; the list tools return a short set of named fields only.
- Documents (packing slips, labels, return slips) and return images are never returned.
- Delivery and billing addresses belong to the shop’s own customers. Lists return
the recipient’s name, company, postal code, city and country.
get_orderandget_shipmentadd phone and e-mail. - Tracking events are capped at the 20 most recent per tracking number.
Orders
Orders with status
error or missing_rate are the ones Webshipper could not
ship; errorMessage says why.
Shipments & tracking
costPrice is what the carrier charges (from the carrier or the account’s cost
sheet); salesPrice is what the customer paid.
Shipping rates & costs
summarize_shipping_costs
Adds up the shipments created in a period per carrier and currency. Reads at most 1,500 shipments.true when the 1,500 cap was reached. Ask for a shorter period rather than reading the totals as complete.One row per carrier and currency, most shipments first:
carrier, currency, shipments, costPrice, salesPrice and withoutCostPrice (shipments with no cost price, left out of costPrice).Quotes and the rate list
Package dimensions are used only when all three of
lengthCm, widthCm and
heightCm are given.
Drop points
find_drop_points
The parcel shops and lockers closest to an address, for a shipping rate or for a carrier’s service. Give eithershippingRateId, or carrierId together
with serviceCode.
At most 20, nearest first:
dropPointId, name, address fields, carrierCode, latitude, longitude and openingHours.Setup & returns
Write safety: guardrail model
The 3 write tools share one confirmation model.- Every write is preview-first. A call without
confirm: truenever changes anything.create_shipmentandupdate_orderread the order first, so a dry-run can already fail with a read error (e.g. a not-found for a wrong id) or with one of the order checks below. Otherwise you get a preview of the exact request and nothing is written. confirm: trueis required to apply, with no exceptions. Re-run the identical call withconfirm: true. See Theconfirmargument.- Bookings and order updates are bound to the preview.
create_shipmentandupdate_orderalso requireexpectedStatefrom the preview on the confirming call. The binding is recomputed from a fresh read of the order; if the order changed in Webshipper, or the arguments differ from the previewed call, the write is refused and nothing is written. - Only orders that can ship. An order that is locked, dispatched, partly
dispatched or cancelled can be neither booked nor updated.
create_shipmentalso refuses an order on hold (release it withupdate_order, statuspending, first) and books only orders with statuspending,errorormissing_rate. An order with no shipping rate needsshippingRateId. - Nothing is deleted or cancelled. There is no tool that deletes or cancels an order or a shipment, fetches or prints labels and documents, books a pickup, creates a return or changes the account’s setup.
- Unknown outcomes are reported. A write that gets no answer says the outcome is unknown; a write Webshipper accepted whose answer could not be read says so. Both ask you to check with a search or get tool before repeating.
Set
true to apply the change in Webshipper. Omit (or false) to get a dry-run
preview. Accepted by every write tool.The 16-character hex value from
preview.state.expectedState. Treat it as
opaque. Required with confirm: true on create_shipment and update_order.Preview shape
When a write is not confirmed, the tool returns this as a normal (non-error) tool result instead of writing to Webshipper:Only on
create_shipment and update_order: the order as it is in Webshipper now (id, visibleRef, status, lockState, order channel, shipping rate, recipient, drop point, line and item counts and the stored delivery address).Write tools
create_shipment
Books one order with its carrier, using the order’s own shipping rate or the one given. This buys postage and can notify the recipient.Book with this shipping rate instead of the order’s own. Required when the order has none (typically
missing_rate).{ booked: true, shipment } with the shipment as search_shipments
shows it, including tracking numbers when the carrier has assigned them.
update_order
Changes one order before it ships. Give at least one ofdeliveryAddress,
shippingRateId and status.
The delivery address fields to change; every field left out keeps its current
value. Fields:
attContact, companyName, address1, address2, zip,
city, state, countryCode, phone, email. At least one field.{ updated: true, order }.
create_order
Creates a manual order in one order channel, e.g. a replacement or a B2B parcel. The order is created with automatic shipment creation switched off, so nothing is booked; book it withcreate_shipment.
The address fields as on
update_order, with address1, zip, city and
countryCode required, and attContact or companyName required.1 to 100 lines, each with
description and quantity (required) and optional
sku, unitPrice, vatPercent, and weight with weightUnit (given
together).{ created: true, order }. A drop point, billing address or sender
address cannot be set.
Errors and timeouts
Tool failures come back as a normal tool result withisError: true and one text
block. Webshipper’s own error text is never quoted (an order’s errorMessage is
data, returned only by the read tools).
Each request to Webshipper times out after 20 seconds, except
quote_carrier_services, which waits up to 30 seconds for the carrier. See
Errors & limits for the protocol-level errors and
rate limits shared by all connectors.