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.superlabel.ca/mcp
Developer MCP — gidsen, webhooks en voorbeeld-API’s voor integrators — https://api.superlabel.ca/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.superlabel.ca/mcp`	Ops-/support-/business-agents	Bearer + optioneel profiel/scopes (volledig indien leeg)
`superroute-developer`	`https://api.superlabel.ca/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": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/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": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/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.superlabel.ca/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": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/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

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: 47 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.

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": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp"
    }
  }
}

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

.mcp.json (met authenticatie)

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/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": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/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": {
    "super-label": {
      "serverUrl": "https://api.superlabel.ca/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.superlabel.ca/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.superlabel.ca/.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.