Conecte Trackberry a su asistente de IA

Objetivo #

Hacerle preguntas a su asistente de IA sobre sus propios envíos y obtener respuestas a partir de datos de Trackberry en vivo: “¿qué contenedores nos van a generar demora esta semana?”, “¿se movió la ETA del envío a Rotterdam?”, “¿a qué envíos les falta el certificado de origen?”.

Para esto, Trackberry ofrece un servidor Model Context Protocol (MCP). MCP es el estándar con el que un asistente como Claude, ChatGPT o Cursor llama a herramientas de otro producto. El asistente decide qué herramienta de Trackberry usar, lee la respuesta y se la explica en lenguaje sencillo.

La conexión es de solo lectura. El asistente puede consultar lo que usted ya ve en Trackberry y no puede crear, cambiar ni eliminar nada.

Qué necesita #

• Una cuenta de Trackberry con acceso a la organización sobre la que quiere preguntar. Todos los planes de Trackberry incluyen el servidor MCP.
• Un asistente compatible con servidores MCP remotos: Claude (web, escritorio o Claude Code), ChatGPT o Cursor. Los conectores personalizados dependen del plan del propio asistente; los pasos de abajo indican dónde.
• La dirección del servidor, que es la misma para todos:

https://trackberry.com/mcp

Hay dos formas de iniciar sesión. Claude, ChatGPT, Claude Code y Cursor lo llevan a Trackberry para aprobar la conexión, y allí elige la organización. No hay que copiar nada: el asistente se registra solo en Trackberry la primera vez que se conecta. Si prefiere no iniciar sesión desde un navegador, o ejecuta el asistente en un servidor que no tiene uno, use un token de API, el mismo token tb_ que se describe en La API de Trackberry.

Conectar Claude o Claude Desktop #

1. Abra Customize → Connectors y haga clic en Add custom connector. La aplicación web y la de escritorio funcionan igual. En el plan Free puede agregar un conector personalizado.
   • En un plan Team o Enterprise, solo un Owner puede agregarlo, en Organization settings → Connectors (Add → Custom). Después, los miembros encuentran Trackberry en Customize → Connectors y hacen clic en Connect.
2. Ingrese la dirección del servidor, https://trackberry.com/mcp. Deje vacíos el ID y el secreto de cliente OAuth. Si Claude le pregunta cómo debe identificarse, elija Register automatically.
3. Su navegador abre una página de Trackberry encabezada con la dirección a la que volverá: claude.ai quiere leer datos de una de sus organizaciones. La aplicación de escritorio también muestra claude.ai. Inicie sesión si todavía no lo ha hecho. Si la dirección no es claude.ai, haga clic en Rechazar.
4. Elija la organización que esta conexión podrá leer y haga clic en Aprobar. Si pertenece a varias, no se preselecciona ninguna.
5. En una conversación, abra el menú +, luego Connectors, y active Trackberry.

Conectar ChatGPT #

1. En ChatGPT en la web, active Developer mode en Settings → Security and login. En un espacio de trabajo Business, Enterprise o Edu, puede que un administrador tenga que permitirlo primero. Los planes que ofrecen el modo de desarrollador los decide OpenAI, así que revise el suyo si no ve el interruptor.
2. Abra Plugins, haga clic en +, póngale un nombre a la conexión e ingrese https://trackberry.com/mcp. Si le pregunta cómo autenticarse, elija OAuth.
3. Apruebe en la página de Trackberry como en los pasos 3 y 4 de arriba. La dirección que aparece es chatgpt.com; rechace si es cualquier otra.
4. En una conversación, elija Developer mode en el menú + y seleccione Trackberry.

La aprobación se mantiene mientras la use. El asistente renueva su acceso en segundo plano cada hora; si pasa 30 días sin usarse, vuelva a conectarlo.

Conectar Claude Code #

Agregue el servidor y luego inicie sesión desde Claude Code:

claude mcp add --transport http trackberry https://trackberry.com/mcp

Inicie Claude Code, escriba /mcp, elija trackberry y seleccione Authenticate. Su navegador abre la misma página de aprobación de Trackberry que arriba y lo devuelve a Claude Code en su propio equipo (la dirección que aparece es localhost o 127.0.0.1). Si el navegador no logra comunicarse con Claude Code después de aprobar, pegue en Claude Code la dirección completa de la barra de direcciones.

Para usar un token, por ejemplo en un servidor sin navegador, cree uno en Configuración de la organización → Tokens de API (/your-slug/settings/api) y páselo como encabezado:

claude mcp add --transport http trackberry https://trackberry.com/mcp \
  --header "Authorization: Bearer tb_your_token"

Ejecute claude mcp list para comprobar que está conectado.

Conectar Cursor #

Con Cursor instalado, haga clic en Add to Cursor. Cursor le pide confirmación y agrega el servidor por usted.

Para agregarlo a mano, ponga esto en ~/.cursor/mcp.json, o en .cursor/mcp.json dentro de un proyecto:

{
  "mcpServers": {
    "trackberry": {
      "url": "https://trackberry.com/mcp"
    }
  }
}

Cursor abre la página de aprobación de Trackberry y vuelve a localhost en su equipo. Para usar un token, cree uno en Configuración de la organización → Tokens de API, guárdelo en una variable de entorno y agréguelo como encabezado, para que el token no quede escrito en el archivo:

{
  "mcpServers": {
    "trackberry": {
      "url": "https://trackberry.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TRACKBERRY_TOKEN}" }
    }
  }
}

Claude Desktop con un token #

La mejor forma de conectar Claude Desktop es con Customize → Connectors, como se explica arriba. Si tiene que usar un token, el asistente comunitario mcp-remote puede hacer de puente entre una entrada de configuración local y el servidor. Anthropic no da soporte a esta configuración, y requiere Node.js. Abra Settings → Developer → Edit Config y agregue:

{
  "mcpServers": {
    "trackberry": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trackberry.com/mcp", "--header", "Authorization: Bearer ${TRACKBERRY_TOKEN}"],
      "env": { "TRACKBERRY_TOKEN": "tb_your_token" }
    }
  }
}

Después de guardar el archivo, cierre Claude Desktop por completo y vuelva a abrirlo.

Qué preguntar #

El asistente funciona mejor con una pregunta concreta sobre sus propios envíos. Algunas que dan buen resultado:

• Días libres. “¿Qué contenedores corren riesgo de demora esta semana y cuántos días le quedan a cada uno?” “¿Qué envíos no tienen condiciones de días libres configuradas?”
• ETA. “¿A qué envíos que llegan la próxima semana se les retrasó la ETA, y cuánto?” “¿Qué pasó con el envío shp_123 desde que salió del Callao?”
• Documentación faltante. “¿Qué envíos en tránsito no tienen factura comercial adjunta?” “¿Quién es el consignatario en el conocimiento de embarque de shp_123?”
• Lo que requiere atención. “¿Hay algún problema con mis envíos hoy?” “¿Hay verificaciones fallidas en las uvas que llegan a Rotterdam?”

También puede pedirle que combine respuestas, por ejemplo que redacte un breve correo de estado para un cliente a partir de la cronología de un envío. Revise las cifras importantes antes de actuar: el asistente lee bien los datos, pero aun así puede resumirlos mal.

Las herramientas #

El asistente ve nueve herramientas y elige entre ellas. Cada una corresponde a una parte de la API y devuelve los mismos campos, salvo que los resultados de búsqueda son breves por defecto, con el último evento de cada envío, para que una vista general de muchos envíos siga siendo rápida.

Los envíos se identifican como shp_ más un número y los documentos como doc_ más un número, los mismos identificadores que en la API. El asistente los encuentra por sí mismo; usted también puede citar uno en una pregunta. Las respuestas sobre un envío enlazan a él en Trackberry, y necesita haber iniciado sesión para abrir el enlace.

Cuando pregunta dónde está un envío o cómo va su trayecto, los asistentes compatibles con MCP Apps también muestran un mapa dentro de la conversación. Es el mismo mapa de la página del envío en Trackberry: la ruta marítima, marcada como recorrida o por recorrer, los puertos de carga, transbordo y descarga, el buque apuntando hacia donde se dirige y el recorrido que ha registrado. Encima aparecen el número de contenedor o de guía aérea, enlazado al envío, su estado, el buque y la naviera, y la ETA con cuánto se ha movido. El mapa aparece una vez por respuesta, junto con la cronología de seguimiento, aunque el asistente también busque el envío.

Qué asistentes muestran el mapa. Lo dibujan Claude en la web, en la aplicación de escritorio y en la aplicación para iOS, y ChatGPT. Claude Code y otros asistentes sin compatibilidad con MCP Apps dan la misma respuesta en texto. El mapa muestra solo las posiciones que ha informado el transportista, así que un envío que todavía no se ha movido indica “Sin posición todavía”.

Los mosaicos de fondo del mapa se cargan desde OpenStreetMap. Su asistente descarga los mosaicos de la zona en pantalla desde los servidores de la OpenStreetMap Foundation, lo que les revela aproximadamente qué parte del mundo está mirando, pero no se les envía ningún dato de los envíos.

Seguridad #

• Solo lectura. No hay herramientas que escriban. Una conexión no puede cambiar un envío, enviar un correo ni eliminar un documento.
• Una organización por conexión. Un token o una aprobación le pertenece a usted y a una organización, y cada respuesta proviene solo de esa organización. Para preguntar por otra, vuelva a conectarse y elíjala. La herramienta list_organizations le indica al asistente qué organización está leyendo.
• Solo lo que usted puede ver. Una conexión lee lo que usted puede leer en Trackberry. Si sale de la organización, o se elimina su membresía, deja de funcionar de inmediato.
• Revóquela cuando quiera. Haga clic en Revocar junto a un token en Configuración de la organización → Tokens de API, o en Desconectar junto a la aplicación en Aplicaciones conectadas, en la misma página, y la conexión se detiene en su siguiente solicitud. Los administradores ven y pueden desconectar las aplicaciones de todos los miembros. Las aprobaciones y desconexiones quedan registradas en el Registro de actividad de la organización.
• Revise a dónde lo devuelven. Cualquier aplicación puede llamarse “Claude”. La página de aprobación empieza por la dirección a la que lo devuelve, que es la parte que no se puede falsificar, y le avisa en rojo cuando no reconoce esa dirección. Rechace si no es el asistente desde el que empezó.
• Trate un token como una contraseña. Cualquiera que lo tenga puede leer los envíos de su organización desde cualquier asistente. No lo guarde en archivos de configuración compartidos ni en repositorios.
• Su asistente ve las respuestas. Lo que devuelve una herramienta se envía al proveedor del asistente como parte de su conversación, bajo las condiciones de ese proveedor. Conecte solo las organizaciones cuyos datos esté dispuesto a comentar con ese asistente.

Límites y errores #

Cada token o conexión puede hacer 600 solicitudes cada 5 minutos, y el servidor comparte los límites descritos en La API de Trackberry. Al asistente se le informa cuando falla una llamada a una herramienta, y por lo general vuelve a intentarlo o le pide lo que falta, por ejemplo un identificador de envío que no existe en su organización.

Los resultados de las herramientas siempre tienen la forma más reciente. A diferencia de la API, no están fijados a una versión y pueden aparecer campos nuevos en cualquier momento. El asistente los interpreta por su significado, así que rara vez se nota, pero no construya un script sobre el servidor MCP. Para eso use la API.

Solución de problemas #

Si no logra avanzar, escriba a support@trackberry.com indicando el asistente que usa y el error que muestra.