Colonna MCP

Panoramica colonna MCP

Questa guida è la colonna MCP Superroute nel Developer Center: entrambi i server, sicurezza degli agenti e catalogo strumenti live.

• User MCP — ordini, percorsi, etichette, digest per agenti ops/support — https://api.miliexpress.com/mcp
• Developer MCP — guide, webhook e API di esempio per integratori — https://api.miliexpress.com/mcp/developer
• Sicurezza: Bearer di connessione, profili/scope, confirm per tool ad alto rischio
• Coda di approvazione umana (propose_write + /mcp-approvals)

Cos'è MCP?

Il Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti IA come Claude, Cursor e ChatGPT di interagire con strumenti e servizi esterni. Permette alla tua IA di eseguire azioni reali — come tracciare un pacco — direttamente nella conversazione.

Configurando il server MCP di Superroute, il tuo assistente IA ottiene accesso agli strumenti logistici senza lasciare il tuo flusso di lavoro.

Due server MCP

Usa il server giusto. Non dare agli agenti non supervisionati il server Developer con accesso completo.

Avvio rapido

Gli strumenti pubblici come il tracciamento dei pacchi funzionano senza autenticazione. Aggiungi questa configurazione al tuo client MCP:

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

Accesso autenticato

Per utilizzare strumenti che richiedono permessi utente, aggiungi il tuo token Bearer API alla configurazione:

Metti i token solo negli header di connessione MCP — mai negli argomenti dei tool o nei prompt.

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

Come ottenere un token API

Chiama l'endpoint di login con le tue credenziali:

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

La risposta includerà il tuo token di accesso:

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

Usa il valore access_token nell'intestazione Authorization della tua configurazione MCP.

Modello di sicurezza agenti

User MCP è pensato per least privilege. Crea token con profilo MCP (default ops sola lettura) o passa header.

Profili (X-MCP-Profile)

Pacchetti di scope con nome. Preferire ops-readonly o support per agenti non supervisionati.

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

Header opzionali

Conferma alto rischio

Questi tool richiedono confirm=true su tools/call (o la coda di approvazione):

• 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

Coda di approvazione umana

Gli agenti non supervisionati propongono le scritture; un umano approva.

1. Agente: propose_write o X-MCP-Require-Approval: 1
2. Umano: MCP Approvals nell’app o list_pending_approvals
3. Umano: approve_pending_write con confirm=true o reject_pending_write

Percorso UI web (login richiesto): /mcp-approvals

Autenticazione Developer MCP

Preferisci Authorization: Bearer sulla connessione. api_token per tool è deprecato e tagliato dopo 2026-12-31.

Strumenti disponibili

I seguenti strumenti sono attualmente disponibili sul server MCP: 93 tool live dal catalogo server

Questa tabella è generata da UserMcpToolCatalog a runtime e resta allineata a tools/list.

Configurazione per client

Seleziona il tuo client IA qui sotto per istruzioni di configurazione personalizzate:

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

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

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

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

Dettagli tecnici

• Protocollo: JSON-RPC 2.0
• Trasporto: HTTP POST (Streamable HTTP)
• Limite di velocità: 60 richieste al minuto
• Tipo di contenuto: application/json
• Punto finale: https://api.miliexpress.com/mcp
• Versioni del protocollo: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  Entrambe le generazioni del protocollo sono servite sullo stesso endpoint: i client che aprono con un handshake initialize e i client stateless che dichiarano la versione a ogni richiesta. Non viene mai emesso un identificativo di sessione.
• Rilevamento OAuth: https://api.miliexpress.com/.well-known/oauth-protected-resource
  Una richiesta non autenticata risponde 401 con un'intestazione WWW-Authenticate che punta al documento di metadati della risorsa protetta.