MCP-column — Agent- en ontwikkelaarshandleiding

Overzicht MCP-column

Deze gids is de Superroute MCP-column in het Developer Center: beide servers, agentbeveiliging en de live toolcatalogus.

User MCP — orders, routes, labels, digests voor ops/support-agents — https://api.miliexpress.com/mcp
Developer MCP — gidsen, webhooks en voorbeeld-API’s voor integrators — https://api.miliexpress.com/mcp/developer
Beveiliging: connection Bearer, profielen/scopes, confirm voor high-risk tools
Menselijke goedkeuringswachtrij (propose_write + /mcp-approvals)

Wat is MCP?

Het Model Context Protocol (MCP) is een open standaard waarmee AI-assistenten zoals Claude, Cursor en ChatGPT kunnen communiceren met externe tools en diensten. Het stelt uw AI in staat om echte acties uit te voeren — zoals een pakket volgen — direct binnen het gesprek.

Door de Superroute MCP-server te configureren, krijgt uw AI-assistent toegang tot logistieke tools zonder uw workflow te verlaten.

Twee MCP-servers

Kies de juiste server. Geef onbeheerde agents geen Developer-server met volledige toegang.

Servernaam	Endpoint	Doelgroep	Auth
`superroute`	`https://api.miliexpress.com/mcp`	Ops-/support-/business-agents	Bearer + optioneel profiel/scopes (volledig indien leeg)
`superroute-developer`	`https://api.miliexpress.com/mcp/developer`	Integratie-ontwikkelaars en coding-agents	Connection Bearer voorkeur; tool api_token wordt uitgefaseerd

Snelstart

Openbare tools zoals pakkettracking werken zonder authenticatie. Voeg deze configuratie toe aan uw MCP-client:

JSON

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

Probeer het! Vraag na het instellen uw AI-assistent: "Volg pakket SR100012345"

Geauthenticeerde toegang

Om tools te gebruiken die gebruikersrechten vereisen, voegt u uw API Bearer-token toe aan de configuratie:

Zet tokens altijd in MCP-connection-headers — nooit in tool-argumenten of prompts.

JSON

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Hoe krijgt u een API-token

Roep het login-eindpunt aan met uw inloggegevens:

Bash

curl -X POST https://api.miliexpress.com/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Het antwoord bevat uw toegangstoken:

JSON Response

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "Bearer",
  "expires_at": "2026-02-20 00:00:00"
}

Gebruik de access_token-waarde in de Authorization-header van uw MCP-configuratie.

Agentbeveiligingsmodel

User MCP is gebouwd voor least privilege. Maak tokens met MCP-profiel (standaard ops alleen-lezen) of stuur headers.

Profielen (X-MCP-Profile)

Benoemde scope-bundels. Kies ops-readonly of support voor onbeheerde agents.

Profiel	Label	Scopes
`ops-readonly`	Ops alleen-lezen	`orders:read, labels:read, routes:read, drivers:read, analytics:read, address:read, approvals:read`
`support`	Support (klantenservice)	`orders:read, analytics:read, address:read, approvals:read`
`ops-write`	Ops schrijven (orders + labels + routes)	`orders:read, orders:write, labels:read, labels:write, routes:read, routes:write, drivers:read, analytics:read, address:read, approvals:read, approvals:write`
`wms-readonly`	WMS alleen-lezen	`wms:read, orders:read`
`datasets-readonly`	Datasets alleen-lezen	`datasets:read`
`alliance-readonly`	Alliance alleen-lezen	`alliance:read`
`full`	Volledige toegang (alle MCP-tools) — niet voor onbeheerde agents	`*`

.mcp.json — aanbevolen agentconfig

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <ops-readonly-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Optionele headers

Header	Doel
`Authorization: Bearer …`	API Bearer-token (connection-niveau).
`X-MCP-Profile`	Profiel: ops-readonly, support, ops-write, wms-readonly, datasets-readonly, alliance-readonly, full.
`X-MCP-Scopes`	Expliciete kommagescheiden scopes (overschrijft profiel).
`X-MCP-Dry-Run: 1`	Schrijftools voorvertonen zonder mutatie.
`X-MCP-Require-Approval: 1`	High-risk writes in wachtrij voor menselijke goedkeuring.

High-risk bevestiging

Deze tools vereisen confirm=true bij tools/call (of de goedkeuringswachtrij):

cancel_order
bulk_create_orders
reroute_to_address
build_route
hold_order
release_order
approve_pending_write
bulk_create_orders_async
get_shipping_detail
download_shipping_label
cancel_shipping_label
submit_shipping_information
end_of_day
uniorder_cancel
uniorder_purchase_label
uniorder_create_batch
uniorder_create_batch_async
pay_shipping_order
cancel_shipping_order
pay_storage_order
cancel_storage_order
pay_shipout
cancel_shipout

Menselijke goedkeuringswachtrij

Onbeheerde agents stellen writes voor; mensen keuren goed.

Agent: propose_write of X-MCP-Require-Approval: 1
Mens: MCP Approvals in de app of list_pending_approvals
Mens: approve_pending_write met confirm=true of reject_pending_write

Web-UI-pad (login vereist): /mcp-approvals

Developer MCP-authenticatie

Gebruik Authorization: Bearer op de verbinding. Per-tool api_token is verouderd en stopt na 2026-12-31.

Beschikbare tools

De volgende tools zijn momenteel beschikbaar op de MCP-server: 93 live tools uit de servercatalogus

Deze tabel komt live uit UserMcpToolCatalog en blijft synchroon met tools/list.

Gereedschap	Authenticatie	Risico	Scopes	Beschrijving
`track_package`	Openbaar	low	`—`	Track a package by its tracking number. Returns delivery status, tracking events timeline, and proof of delivery if available.
`otep_tracking`	Openbaar	low	`—`	Get the unified OTEP (Open Tracking Event Protocol) timeline for a tracking number — self-delivery, third-party and carrier events normalize...
`get_capabilities`	Openbaar	low	`—`	List MCP tools available to the current connection, with risk level, required scopes, and whether confirm=true is needed. Call this first wh...
`get_orders`	Vereist	low	`orders:read`	List orders with filtering and pagination. Returns order details including status, tracking, and delivery info.
`get_order_detail`	Vereist	low	`orders:read`	Get full details of a specific order by ID, including address, status, packages, and tracking info.
`find_order`	Vereist	low	`orders:read`	Fuzzy-find orders across tracking number, external tracking, ref, recipient name, and phone in a single query. Use this instead of get_order...
`get_operation_events`	Vereist	low	`orders:read`	Get the full audit trail for orders — every status change, who performed it, GPS coordinates, and photos.
`create_order`	Vereist	medium	`orders:write`	Create a delivery/pickup order. D=delivery (warehouse→customer), P=pickup (customer→warehouse), P2P=peer-to-peer. Returns order ID and track...
`cancel_order` confirm	Vereist	high	`orders:write`	Cancel an existing order by order ID. Only works for orders not yet delivered.
`bulk_create_orders` confirm	Vereist	high	`orders:write`	Create up to 100 delivery orders in one call. Returns a per-order success/failure summary; partial failures do not abort the batch unless st...
`reroute_to_address` confirm	Vereist	high	`orders:write`	Change the delivery address of an order that has not been picked up yet: cancels the original order and recreates it with the new address. R...
`update_delivery_instruction`	Vereist	medium	`orders:write`	Update only the delivery_instruction field on an existing order (PATCH). Safer than full order rewrite.
`update_order_note`	Vereist	medium	`orders:write`	Update only the internal note field on an existing order (PATCH).
`update_time_window_by_refs`	Vereist	medium	`orders:write`	Bulk-update delivery time windows (and optional schedule_date) for orders identified by external refs.
`hold_order` confirm	Vereist	high	`orders:write`	Put an order on HOLD so it is not dispatched until release_order. HIGH-RISK: requires confirm=true.
`release_order` confirm	Vereist	high	`orders:write`	Release an order from HOLD back to NEW_ORDER. HIGH-RISK: requires confirm=true.
`propose_write`	Vereist	low	`approvals:read`	Queue a write/high-risk tool for human approval instead of executing it. Reviewers use list_pending_approvals + approve_pending_write.
`list_pending_approvals`	Vereist	low	`approvals:read`	List pending MCP write approvals for this business (or mine_only).
`approve_pending_write` confirm	Vereist	high	`approvals:write`	Approve and execute a pending write proposal. HIGH-RISK: requires confirm=true. Reviewer must have scopes for the underlying tool.
`reject_pending_write`	Vereist	medium	`approvals:write`	Reject a pending write proposal without executing it.
`get_routes`	Vereist	low	`routes:read`	List delivery routes with their status, assigned driver, and order count.
`get_route_detail`	Vereist	low	`routes:read`	Get one route with its stop/order list. Prefer this over get_routes when you already know route_id.
`get_drivers`	Vereist	low	`drivers:read`	List drivers for the authenticated business (ids, names, capacity defaults). Use driver id with get_driver_routes_today or route tools.
`get_driver_routes_today`	Vereist	low	`routes:read, drivers:read`	Orders assigned to a driver on a given date (defaults to today). Useful for "what is driver X running today?"
`get_build_route_options`	Vereist	low	`routes:read`	List routing engines, balance modes, capacity types, and defaults before calling build_route.
`build_route` confirm	Vereist	high	`routes:write`	Build/optimize a delivery route (POST /api/v3/client/build-route). HIGH-RISK: assigns orders to drivers. Call get_build_route_options first....
`order_snapshot`	Vereist	low	`orders:read`	One-call order context for support: order detail + operation events + public tracking (when tracking number is known). Pass order_id or trac...
`list_exceptions`	Vereist	low	`orders:read`	List failed/returned/exception-like orders for a schedule date (default today). Read-only ops triage helper.
`get_shipping_methods`	Vereist	low	`labels:read`	List available shipping carriers/methods. Returns IDs and names — use the ID for rate/label tools.
`get_shipping_rate`	Vereist	low	`labels:read`	Get a shipping cost quote. Dry-run — no label created. Returns rate options with pricing and transit time.
`create_shipping_label`	Vereist	medium	`labels:write`	Book a shipment with a carrier and generate a shipping label with tracking numbers.
`quote_and_ship`	Vereist	medium	`labels:write`	One-shot: rate across all enabled carriers, pick the best one by strategy, create the shipping label, return tracking number. Saves 3+ tool...
`compare_all_carriers`	Vereist	low	`labels:read`	Get rate quotes from every enabled carrier for the same shipment, in one call. Returns a sorted comparison (cheapest first) with price + tra...
`search_address`	Vereist	low	`address:read`	Search and resolve addresses by postal code or free-text query. Returns structured address suggestions.
`daily_digest`	Vereist	low	`analytics:read`	One-call summary of today's logistics activity: total orders, by status, exceptions (failed/returned), pending pickups. Designed as the firs...
`get_orders_summary`	Vereist	low	`analytics:read`	Aggregate order metrics over a time window: counts by status, top carriers, on-time rate, exception count. Use period=today\|week\|month or pa...
`get_account_credits`	Vereist	low	`analytics:read`	Get the authenticated customer's wallet balance, currency, and recent topup history. Customer (B2C) accounts only — returns an error for cli...
`get_warehouses`	Vereist	low	`wms:read`	List WMS warehouses available to the authenticated business.
`get_inventory`	Vereist	low	`wms:read`	Query WMS inventory (POST /api/v1/wms/inventory). Pass filters supported by the inventory API (sku, warehouse_id, etc.).
`list_datasets`	Vereist	low	`datasets:read`	List custom datasets available to the business.
`get_dataset`	Vereist	low	`datasets:read`	Get one dataset by id (metadata/columns).
`list_dataset_groups`	Vereist	low	`datasets:read`	List groups inside a dataset.
`search_dataset_records`	Vereist	low	`datasets:read`	Search records across groups in a dataset (POST .../search).
`list_alliances`	Vereist	low	`alliance:read`	List alliances the authenticated business belongs to.
`get_alliance`	Vereist	low	`alliance:read`	Get one alliance by id.
`list_alliance_members`	Vereist	low	`alliance:read`	List members of an alliance.
`list_accessible_clients`	Vereist	low	`alliance:read`	List clients accessible via alliance partnerships.
`quote_delivery`	Vereist	low	`orders:read`	Get the local delivery price for a shipment before creating the order (POST /api/v1/orders/rate). No order is created.
`print_local_label`	Vereist	low	`orders:read`	Get the printable label of a local delivery order as a base64 PDF, with its label code and tracking numbers (POST /api/v2/shipping/getShippi...
`bulk_create_orders_async` confirm	Vereist	high	`orders:write`	Queue a large batch of delivery orders for creation (POST /api/v1/client/batchOrderCreateAsync). Returns an asyncId at once; read the per-or...
`get_async_batch_result`	Vereist	low	`orders:read`	Read the status and per-order results of a batch queued with bulk_create_orders_async (GET /api/v1/client/async/{id}).
`get_shipping_detail` confirm	Vereist	high	`labels:write`	Get the carrier shipping detail of a label order: tracking numbers, price and the label (POST /api/v1/labelservice/getShippingDetail). The f...
`download_shipping_label` confirm	Vereist	high	`labels:write`	Download the label PDF of an order as base64 (POST /api/v1/shipping/getShippingLabel with base64). For a carrier label order whose label was...
`cancel_shipping_label` confirm	Vereist	high	`labels:write`	Cancel (void) a carrier label with the carrier (POST /api/v1/labelservice/cancelShippingLabel). Pass the order id, or one package tracking n...
`submit_shipping_information` confirm	Vereist	high	`labels:write`	Submit the shipping information of one or more label orders to their carriers (POST /api/v1/labelservice/submitShippingInformation).
`end_of_day` confirm	Vereist	high	`labels:write`	Close the day with the carriers: submit the shipping information of every open label order (POST /api/v1/labelservice/endofday).
`uniorder_rate`	Vereist	low	`uniorder:read`	Quote one shipment across self delivery and, with quote_labels=true, every label carrier service of the account (POST /api/v1/uniorder/rate)...
`uniorder_create`	Vereist	medium	`uniorder:write`	Create an order at a rate_id from uniorder_rate (POST /api/v1/uniorder). The rate decides the service: a self delivery order, or a label ord...
`uniorder_get`	Vereist	low	`uniorder:read`	Read one uniorder order in the uniorder shape (GET /api/v1/uniorder/{orderId}).
`uniorder_label`	Vereist	low	`uniorder:read`	Get the label PDF of a uniorder order, base64 (GET /api/v1/uniorder/{orderId}/label).
`uniorder_tracking`	Vereist	low	`uniorder:read`	Get the tracking timeline of a uniorder order (GET /api/v1/uniorder/{orderId}/tracking).
`uniorder_cancel` confirm	Vereist	high	`uniorder:write`	Cancel a uniorder order, self delivery or label (POST /api/v1/uniorder/{orderId}/cancel). A label order voids its carrier label.
`uniorder_purchase_label` confirm	Vereist	high	`uniorder:write`	Buy the carrier label of a uniorder label order that was kept without one (LABEL_PURCHASE_FAILED), at the service chosen at create or at a n...
`uniorder_rate_batch`	Vereist	low	`uniorder:read`	Quote up to 20 shipments in one call (POST /api/v1/uniorder/rate/batch). Each shipment takes the uniorder_rate shape plus an optional refere...
`uniorder_create_batch` confirm	Vereist	high	`uniorder:write`	Create up to 20 orders in one call, each at its own rate_id (POST /api/v1/uniorder/batch). Returns a result per order.
`uniorder_rate_batch_async`	Vereist	low	`uniorder:read`	Queue up to 500 shipments to quote (POST /api/v1/uniorder/rate/batch-async). Returns a job id; read the quotes with uniorder_job.
`uniorder_create_batch_async` confirm	Vereist	high	`uniorder:write`	Queue up to 500 orders to create, each at its own rate_id (POST /api/v1/uniorder/batch-async). Returns a job id; read the results with unior...
`uniorder_job`	Vereist	low	`uniorder:read`	Read a queued uniorder batch and, once done, its results (GET /api/v1/uniorder/jobs/{jobId}).
`list_shipping_services`	Vereist	low	`customer_shipping:read`	List the shipping services the customer may order (GET /api/v1/customer/shipping-orders/services). Step 1 of a shipping order. Needs a custo...
`get_shipping_service_config`	Vereist	low	`customer_shipping:read`	Get one shipping service's order form: warehouses, surcharges, packaging, supplies, units and form fields (GET /api/v1/customer/shipping-ord...
`estimate_shipping_order`	Vereist	low	`customer_shipping:read`	Estimate the price of a shipping order on a service (POST /api/v1/customer/shipping-orders/services/{serviceCode}/estimate-price). No order...
`create_shipping_order`	Vereist	medium	`customer_shipping:write`	Create a shipping order on a service (POST /api/v1/customer/shipping-orders/services/{serviceCode}/orders). Note the package list field is `...
`pay_shipping_order` confirm	Vereist	high	`customer_shipping:write`	Pay the full remaining balance of a shipping order from the customer wallet (POST /api/v1/customer/shipping-orders/{id}/pay). A fully paid p...
`get_shipping_order`	Vereist	low	`customer_shipping:read`	Get one shipping order of the customer (GET /api/v1/customer/shipping-orders/{id}). Needs a customer account token.
`list_shipping_orders`	Vereist	low	`customer_shipping:read`	List the customer's shipping orders on one service, paginated (GET /api/v1/customer/shipping-orders/services/{serviceCode}/orders). Needs a...
`cancel_shipping_order` confirm	Vereist	high	`customer_shipping:write`	Cancel a pending or confirmed shipping order of the customer (POST /api/v1/customer/shipping-orders/{id}/cancel). Needs a customer account t...
`get_storage_order_config`	Vereist	low	`storage:read`	Get what a storage order form needs: warehouses, packaging, supplies, pickup timeframes, units, surcharges and form fields (GET /api/v1/cust...
`quote_storage_order`	Vereist	low	`storage:read`	Calculate the price of a storage order before creating it (POST /api/v1/customer/storage-orders/calculate-price). Storage order form fields...
`create_storage_order`	Vereist	medium	`storage:write`	Create a storage order (POST /api/v1/customer/storage-orders). Storage order form fields as returned by get_storage_order_config: warehouse_...
`pay_storage_order` confirm	Vereist	high	`storage:write`	Pay a storage order from the customer wallet (POST /api/v1/customer/storage-orders/{id}/pay). Needs a customer account token.
`get_storage_order`	Vereist	low	`storage:read`	Get one storage order of the customer, with can_edit, can_cancel and each package's received flag (GET /api/v1/customer/storage-orders/{id})...
`list_storage_orders`	Vereist	low	`storage:read`	List the customer's storage orders, paginated (GET /api/v1/customer/storage-orders). Needs a customer account token.
`cancel_storage_order` confirm	Vereist	high	`storage:write`	Cancel a storage order of the customer while its status allows it (POST /api/v1/customer/storage-orders/{id}/cancel). Needs a customer accou...
`list_stored_packages`	Vereist	low	`storage:read`	List the customer's stored packages that can be shipped out: received, not stocked out and not held by another ship-out, grouped by storage...
`list_shipout_services`	Vereist	low	`storage:read`	List the shipping services that ship out from a warehouse (GET /api/v1/customer/shipout-orders/services). pricing_method 1 = priced at once,...
`estimate_shipout`	Vereist	low	`storage:read`	Estimate the price of a ship-out (POST /api/v1/customer/shipout-orders/services/{serviceCode}/estimate). A manually priced service answers h...
`create_shipout`	Vereist	medium	`storage:write`	Create a ship-out of stored packages from one warehouse (POST /api/v1/customer/shipout-orders/services/{serviceCode}/orders). The chosen pac...
`pay_shipout` confirm	Vereist	high	`storage:write`	Pay a priced ship-out from the customer wallet (POST /api/v1/customer/shipout-orders/{id}/pay). Default is the full remaining balance. Needs...
`get_shipout`	Vereist	low	`storage:read`	Get one ship-out of the customer with paid amount, remaining balance, can_be_paid, can_be_cancelled and its packages (GET /api/v1/customer/s...
`list_shipouts`	Vereist	low	`storage:read`	List the customer's ship-outs, paginated (GET /api/v1/customer/shipout-orders). Needs a customer account token.
`cancel_shipout` confirm	Vereist	high	`storage:write`	Cancel a pending or confirmed ship-out and release its stored packages (POST /api/v1/customer/shipout-orders/{id}/cancel). A payment is not...
`otep_client_tracking`	Vereist	low	`orders:read`	Get the OTEP timeline and details (addresses, dates, proof of delivery, item counts) of one of your own shipments: a parcel tracking number,...
`otep_client_locker_storage`	Vereist	low	`orders:read`	Get the OTEP timeline (storage profile) and details of one of your locker storage rentals, by rental id. Requires a token.

Clientspecifieke installatie

Selecteer hieronder uw AI-client voor aangepaste installatie-instructies:

Claude Code

Claude Code leest de MCP-configuratie uit een .mcp.json-bestand in de projectroot of thuismap.

Maak een .mcp.json-bestand aan in uw projectroot (of ~/.claude/.mcp.json voor globale toegang).
Voeg de volgende configuratie toe:

.mcp.json

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

Om geauthenticeerde tools te gebruiken, voegt u het headers-veld toe:

.mcp.json (met authenticatie)

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Cursor

Cursor ondersteunt MCP-servers via de ingebouwde configuratie.

Maak een .cursor/mcp.json-bestand aan in uw projectroot.
Voeg de volgende configuratie toe:
Herstart Cursor om de nieuwe MCP-server te laden.

.cursor/mcp.json

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

Windsurf

Windsurf gebruikt een globaal MCP-configuratiebestand.

Bewerk ~/.codeium/windsurf/mcp_config.json (maak het aan als het niet bestaat).
Voeg de volgende configuratie toe:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mili-express": {
      "serverUrl": "https://api.miliexpress.com/mcp"
    }
  }
}

ChatGPT

ChatGPT ondersteunt MCP-verbindingen voor Plus-, Pro- en Team-gebruikers.

Open ChatGPT en ga naar Instellingen.
Navigeer naar de sectie "Verbonden apps" of "Tools".
Voeg een nieuwe MCP-server toe met de hierboven weergegeven eindpunt-URL.

De MCP-ondersteuning van ChatGPT kan variëren afhankelijk van uw abonnement en regio. Raadpleeg de OpenAI-documentatie voor de meest recente instructies.

Technische details

Protocol: JSON-RPC 2.0
Vervoer: HTTP POST (Streamable HTTP)
Snelheidslimiet: 60 verzoeken per minuut
Inhoudstype: application/json
Eindpunt: https://api.miliexpress.com/mcp
Protocolversies: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
Beide protocolgeneraties worden op hetzelfde eindpunt bediend: clients die met een initialize-handshake beginnen en stateless clients die de versie bij elke aanvraag opgeven. Er wordt nooit een sessie-id uitgegeven.
OAuth-ontdekking: https://api.miliexpress.com/.well-known/oauth-protected-resource
Een niet-geauthenticeerde aanvraag antwoordt met 401 en een WWW-Authenticate-header die naar het metadatadocument van de beveiligde resource verwijst.