Columna MCP

Resumen de la columna MCP

Esta guía es la columna MCP de Superroute en el Centro de Desarrolladores: ambos servidores, seguridad de agentes y el catálogo de herramientas en vivo.

• User MCP — pedidos, rutas, etiquetas y resúmenes para agentes de ops/soporte — https://api.miliexpress.com/mcp
• Developer MCP — guías, webhooks y APIs de ejemplo para integradores — https://api.miliexpress.com/mcp/developer
• Seguridad: Bearer de conexión, perfiles/scopes, confirm en herramientas de alto riesgo
• Cola de aprobación humana (propose_write + /mcp-approvals)

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite a asistentes de IA como Claude, Cursor y ChatGPT interactuar con herramientas y servicios externos. Permite que su IA realice acciones reales, como rastrear un paquete, directamente dentro de la conversación.

Al configurar el servidor MCP de Superroute, su asistente de IA obtiene acceso a herramientas logísticas sin abandonar su flujo de trabajo.

Dos servidores MCP

Use el servidor adecuado. No dé a agentes desatendidos el servidor Developer con acceso total.

Inicio rápido

Las herramientas públicas como el rastreo de paquetes funcionan sin autenticación. Agregue esta configuración a su cliente MCP:

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

Acceso autenticado

Para usar herramientas que requieren permisos de usuario, agregue su token Bearer de API a la configuración:

Ponga los tokens solo en los encabezados de conexión MCP — nunca en argumentos de herramientas ni prompts.

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

Cómo obtener un token de API

Llame al endpoint de inicio de sesión con sus credenciales:

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 respuesta incluirá su token de acceso:

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

Use el valor de access_token en el encabezado Authorization de su configuración MCP.

Modelo de seguridad del agente

User MCP está pensado para privilegio mínimo. Cree tokens con perfil MCP (predeterminado: ops solo lectura) o pase headers.

Perfiles (X-MCP-Profile)

Paquetes de scopes con nombre. Prefiera ops-readonly o support para agentes desatendidos.

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

Encabezados opcionales

Confirmación de alto riesgo

Estas herramientas requieren confirm=true en tools/call (o la cola de aprobación):

• 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

Cola de aprobación humana

Los agentes desatendidos deben proponer escrituras; un humano aprueba.

1. Agente: propose_write o X-MCP-Require-Approval: 1
2. Humano: MCP Approvals en la app o list_pending_approvals
3. Humano: approve_pending_write con confirm=true o reject_pending_write

Ruta de la UI web (requiere inicio de sesión): /mcp-approvals

Autenticación Developer MCP

Prefiera Authorization: Bearer en la conexión. api_token por herramienta está obsoleto y se corta tras 2026-12-31.

Herramientas disponibles

Las siguientes herramientas están actualmente disponibles en el servidor MCP: 93 herramientas en vivo del catálogo del servidor

Esta tabla se genera desde UserMcpToolCatalog en tiempo de solicitud y se mantiene sincronizada con tools/list.

Configuración por cliente

Seleccione su cliente de IA a continuación para obtener instrucciones de configuración específicas:

{
  "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"
    }
  }
}

Detalles técnicos

• Protocolo: JSON-RPC 2.0
• Transporte: HTTP POST (Streamable HTTP)
• Límite de tasa: 60 solicitudes por minuto
• Tipo de contenido: application/json
• Punto final: https://api.miliexpress.com/mcp
• Versiones del protocolo: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  Ambas generaciones del protocolo se atienden en el mismo endpoint: clientes que abren con un handshake initialize y clientes sin estado que declaran la versión en cada solicitud. Nunca se emite un identificador de sesión.
• Descubrimiento OAuth: https://api.miliexpress.com/.well-known/oauth-protected-resource
  Una solicitud sin autenticar responde 401 con una cabecera WWW-Authenticate que apunta al documento de metadatos del recurso protegido.