MCP Server Beta

Por qué importa

El Model Context Protocol convirtió a los agentes IA en una nueva interfaz para operar software B2B: en vez de que cada cliente escriba una integración, el agente descubre lo que tu plataforma sabe hacer y lo ejecuta conversando. El MCP Server de +Simple lleva eso a la logística — sin SDKs, sin glue code, sin esperar a un equipo de ingeniería.

¿Qué es MCP?

Model Context Protocol es un estándar abierto para que las aplicaciones de IA descubran y usen herramientas externas. Cualquier cliente compatible (Claude Desktop, Claude en web, Cursor, Cline, etc.) puede conectarse a un servidor MCP y usar las tools que expone.

El servidor MCP de +Simple es un adaptador puro sobre nuestra API REST /v1: cada operación de la API se convierte automáticamente en una tool que el agente puede invocar. No hay lógica nueva ni un contrato aparte — es la misma API que documenta el API Reference, expuesta en el lenguaje de los agentes.

Cómo funciona

Las 73 tools se generan a partir del mismo contrato OpenAPI que documenta la API REST. Esto garantiza cero drift: si la API cambia, las tools se actualizan en la misma versión del servidor, sin trabajo manual.

El flujo de una conversación es siempre el mismo:

La autenticación, los scopes, el rate limiting y el audit log son exactamente los mismos que los de la API REST: el MCP no abre una puerta nueva, reusa la que ya existe.

Conectá en 2 minutos

La forma recomendada es el conector remoto: la API key viaja en la URL del conector y el servidor resuelve tu empresa y permisos por request. No hay que instalar nada.

https://api.massimple.la/mcp/k/<TU_API_KEY>

Alternativa: servidor local (stdio)

Para entornos de escritorio (Claude Desktop, Cursor) también podés correr el servidor localmente vía stdio, apuntándolo al entorno que quieras:

{
  "mcpServers": {
    "massimple": {
      "command": "npx",
      "args": ["@massimple/mcp-server"],
      "env": {
        "MASSIMPLE_API_KEY": "mss_test_...",
        "MASSIMPLE_BASE_URL": "https://api.massimple.la/v1"
      }
    }
  }
}

Autenticación y entornos

La API key identifica a tu empresa y trae los scopes que definís al crearla. Cada tool call se ejecuta con esos permisos y queda acotada a tu empresa — un agente nunca ve datos de otra.

Sanity check inmediato: pedile al agente "¿a qué empresa apunta mi conexión?" y va a llamar get_whoami:

{
  "application": {
    "id": "...",
    "name": "Mi asistente",
    "env": "test",
    "scopes": ["shipments:read", "routes:read", "analytics:read"]
  },
  "company_id": "..."
}

Ejemplos de uso

Cada ejemplo muestra el pedido en lenguaje natural, la tool call que arma el agente y la respuesta que devuelve +Simple.

Consultar métricas de la operación

El agente llama get_operations_summary (scope analytics:read). Devuelve una foto now más ventanas de 24h/7d/30d con su rango exacto — los mismos números que ves en el dashboard:

{
  "as_of": "2026-07-12T14:30:00.000Z",
  "sla_minutes": 240,
  "now": {
    "active_routes": 12,
    "active_assignments": 9
  },
  "windows": {
    "24h": {
      "from": "2026-07-11T14:30:00.000Z",
      "to": "2026-07-12T14:30:00.000Z",
      "shipments_by_status": { "pending": 34, "in_route": 21, "delivered": 78 },
      "shipments_with_activity": 133,
      "sla_performance": 0.94,
      "completion_rate": 0.97,
      "avg_delivery_minutes": 186
    }
  },
  "hint": "Para desglose por hora/ruta y export, usá el Dashboard."
}

Listar envíos por estado

El agente llama list_shipments con filtros (scope shipments:read). Además de status y date, soporta rangos created_from/created_to y updated_from/updated_to:

// tools/call → list_shipments
{
  "status": "pending",
  "created_from": "2026-07-06",
  "created_to": "2026-07-12",
  "limit": 50
}

Respuesta (listado paginado):

{
  "data": [
    {
      "_id": "...",
      "trackingNumber": "MS-2026-000123",
      "status": "pending",
      "destination": { "destinyName": "Juan Pérez", "address": "Av. Corrientes 1234, CABA" },
      "createdAt": "2026-07-10T11:02:00.000Z"
    }
  ],
  "pagination": { "total": 34, "limit": 50, "offset": 0 }
}

Crear un envío

Con scope shipments:write, el agente llama create_shipment:

// tools/call → create_shipment
{
  "originDistributionCenter": "<ID-DC>",
  "destination": {
    "destinyName": "Juan Pérez",
    "address": "Av. Corrientes 1234, CABA",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "contactPhone": "+5491155557777"
  },
  "content": "Caja con dos productos",
  "amountToCollect": 0,
  "scheduledDate": "2026-07-13",
  "status": "pending"
}

Respuesta 201 con el envío creado, incluyendo _id y trackingNumber autogenerado. El agente te confirma el número de seguimiento.

Flujo completo de distribución

Con un rol de Operador de distribución, un agente puede encadenar tools en una sola conversación: list_available_shipments → create_route → optimize_route → create_assignment (conductor + vehículo). Vos describís el objetivo; el agente resuelve el orden.

Catálogo de tools

73 tools, una por cada operación de la API. Los nombres son el operationId en snake_case. Para el detalle de parámetros y respuestas de cada una, mirá el API Reference (mismo contrato).

Envíos · 15

Rutas · 16

Vehículos · 9

Conductores · 11

Asignaciones · 10

Webhooks · 7

Eventos, métricas y sistema · 5

Roles y scopes

Una key MCP lleva un bundle de scopes que define qué puede hacer el agente. Al crearla en el dashboard elegís un preset de rol; podés ajustar los scopes finos después. Las keys MCP arrancan en Solo lectura por default.

Formato de respuestas

El servidor devuelve datos, no prosa: el JSON crudo de la API, para que el agente lo interprete con precisión. Algunos principios de diseño:

Seguridad

• Least-privilege por default. Las keys MCP arrancan read-only; los scopes de escritura son opt-in explícito.
• Aislamiento por empresa. Cada tool call queda acotado al company_id de la key. Un agente nunca ve datos de otra empresa.
• Rate limiting. Límite de requests por minuto por key, con Retry-After al excederlo.
• Audit log. Cada request queda registrado (empresa, tipo de key, endpoint, status) para trazabilidad.
• Revocable y rotable. Podés desactivar o rotar cualquier key desde el dashboard en cualquier momento.
• TLS end-to-end. La key viaja en la URL del conector sobre HTTPS; tratala como un secreto.

Límites actuales

El MCP está en beta por invitación. Para ser transparentes sobre lo que todavía no hace:

• Sin OAuth / identidad de usuario. La key identifica a la empresa, no a la persona. El "rol" es el bundle de scopes de la key, no el rol real de un usuario logueado. El login por usuario (SSO nativo en Claude) llega en una fase posterior.
• Solo modo path en el conector. La forma soportada es /mcp/k/<key> en la URL. Los modos header (Authorization: Bearer) y query (?k=) no están disponibles en el dominio actual.
• Sin streaming server→cliente (SSE). El transporte es JSON-RPC stateless: una request, una respuesta. No hay notificaciones push desde el servidor.
• Sin data-scoping por centro. Los presets dan lectura a nivel empresa; acotar a un centro de distribución específico llega con la fase de OAuth.
• Entorno. En beta por invitación; el acceso general (GA) llega después. Escribinos para sumarte.

Recursos

• API Reference — el contrato completo del que se generan las tools.
• Guía ultra simple — integración directa con la API REST en 5 pasos.
• Contactanos — para acceso a la beta, el paquete local o coordinar producción.