Tronco logo

Docs de API y MCP

Guía de integración

Docs de API y MCP

Conecta un agente de IA o tu propio script con Tronco sin automatizar la interfaz web. Parte con el puente MCP local o llama la API HTTP directamente cuando necesites control total.

Si tu herramienta puede leer un contrato de API, usa el documento canónico en formato máquina.

Abrir el JSON OpenAPI

Dos formas de conectar

API HTTP

Usa la API con bearer token para escribir un script, integrar otro servicio o controlar tú las solicitudes. Las operaciones de logs quedan limitadas a la persona dueña del token personal.

Puente MCP local

El puente de Node.js por stdio permite que un cliente compatible con MCP llame a Tronco como herramientas nativas. Mantiene el token en el entorno del cliente y reenvía las operaciones de logs a la API HTTP.

Recomendado: crea un token personal, configura el puente local y luego prueba la solicitud curl para crear un log que aparece más abajo.

Inicio rápido

El puente es un proceso local. No expone un servidor público: tu cliente MCP lo inicia y se comunica por la entrada y salida estándar.

  1. 1. Crea un token personal

    Inicia sesión en Tronco y abre Configuración → Integraciones con agentes. Crea un token con un nombre descriptivo. El valor completo se muestra una sola vez.

    Abrir configuración

  2. 2. Configura las dos variables de entorno

    Agrega estos valores a la configuración del cliente MCP. Usa el origen de tu Tronco desplegado y el token personal que acabas de crear.

    TRONCO_API_URL
    El origen http(s) absoluto de tu app Tronco, por ejemplo https://tu-tronco.example.
    TRONCO_MCP_TOKEN
    El token personal trn_live_.... Trátalo como una contraseña y nunca lo subas a un repositorio.

  3. 3. Configura tu cliente MCP

    Agrega el JSON de configuración de la sección siguiente en tu cliente MCP. Reemplaza la ruta de ejemplo por la ruta absoluta de este repositorio.

  4. 4. Empieza a usar las herramientas

    Reinicia o reconecta el cliente MCP y usa tronco_create_log para una actividad o tronco_sync_logs para un lote. Verifica el resultado con tronco_list_logs o tronco_get_log.

Autenticación y seguridad del token

Hay dos flujos de autenticación distintos. El puente stdio y los endpoints HTTP de logs usan un token bearer personal; la gestión de tokens depende de la sesión de navegador de Clerk.

API de logs: bearer token

Envía Authorization: Bearer trn_live_... en cada solicitud a /api/mcp/logs. Los tokens pertenecen a un usuario, se pueden revocar desde Configuración y los revocados dejan de funcionar al instante.

Gestión de tokens: sesión Clerk

GET/POST /api/mcp/tokens y DELETE /api/mcp/tokens/:id usan la sesión web autenticada. Sirven para crear, listar y revocar tokens desde la cuenta, no para configurar el puente stdio.

Mantén el token privado. No lo pongas en código del navegador, no lo subas a Git ni lo pegues en logs. Si se filtra, revócalo en Configuración y crea uno nuevo.

Ejemplos de la API HTTP

Estos ejemplos usan TRONCO_API_URL y TRONCO_MCP_TOKEN desde tu entorno de shell. Cada solicitud de logs necesita el header bearer.

1. Crear un log

La solicitud necesita date, timePeriod, content y people. timePeriod puede ser am, pm o full_day; content admite 10–5000 caracteres y people es un string.

curl -X POST "https://troncoapp.cl/api/mcp/logs" \
  -H "Authorization: Bearer $TRONCO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: sprint-review-2026-09-02" \
  --data '{
    "date": "2026-09-02",
    "timePeriod": "pm",
    "content": "Closed the release checklist with the team.",
    "people": "Ana, Luis",
    "idempotencyKey": "sprint-review-2026-09-02"
  }'

2. Sincronizar logs en masa

Envía entre 1 y 100 logs, cada uno con un idempotencyKey estable del sistema de origen. Las claves existentes se omiten, nunca se actualizan y cada elemento informa su resultado.

curl -X POST "https://troncoapp.cl/api/mcp/logs-sync" \
  -H "Authorization: Bearer $TRONCO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "logs": [
      {
        "idempotencyKey": "notion:page-123",
        "date": "2026-09-02",
        "timePeriod": "pm",
        "content": "Closed the release checklist with the team.",
        "people": "Ana, Luis"
      }
    ]
  }'

3. Listar logs

Filtra por una fecha exacta o por un rango inclusivo from/to. limit vale 20 por defecto y puede ir de 1 a 100.

curl "https://troncoapp.cl/api/mcp/logs?from=2026-09-01&to=2026-09-02&limit=20" \
  -H "Authorization: Bearer $TRONCO_MCP_TOKEN"

4. Obtener un log

Usa como parámetro de consulta el id que devuelve Tronco. La ruta es /api/mcp/logs?id=...; no existe una ruta /api/mcp/logs/:id.

LOG_ID="mcp_replace_with_the_returned_id"
curl "https://troncoapp.cl/api/mcp/logs?id=$LOG_ID" \
  -H "Authorization: Bearer $TRONCO_MCP_TOKEN"
Idempotencia: envía la clave estable en el body JSON o en el header X-Idempotency-Key; el header gana si mandas ambos. Reintentar la misma clave con los mismos datos devuelve el log original con HTTP 200 y created: false. Reutilizarla con datos distintos devuelve HTTP 409.

Puente MCP local

El puente vive en mcp/tronco-server.mjs y usa solo módulos estándar de Node.js. Habla MCP por stdio y mapea las cuatro herramientas disponibles a la API HTTP de logs.

Endpoint MCP remoto

Conecta un cliente compatible con MCP directamente a Tronco mediante HTTPS. Usa el mismo token personal en el encabezado Authorization; no necesitas instalar un puente local.

{
  "mcpServers": {
    "troncoapp": {
      "url": "https://troncoapp.cl/api/mcp",
      "headers": {
        "Authorization": "Bearer paste-your-personal-token-here"
      }
    }
  }
}

Configuración del cliente MCP

Pega una configuración como esta en tu cliente MCP y reemplaza la ruta, la URL de la app y los placeholders del token. No compartas la configuración completa.

{
  "mcpServers": {
    "troncoapp": {
      "command": "node",
      "args": ["$HOME/.troncoapp/tronco-server.mjs"],
      "env": {
        "TRONCO_API_URL": "https://troncoapp.cl",
        "TRONCO_MCP_TOKEN": "paste-your-personal-token-here"
      }
    }
  }
}

Herramientas disponibles

tronco_create_log

Crea un log con date, timePeriod, content y people. El idempotencyKey opcional hace seguros los reintentos y mapea a POST /api/mcp/logs.

tronco_sync_logs

Sincroniza hasta 100 logs con clave estable. Crea los que faltan, omite los existentes, nunca los actualiza y devuelve el estado de cada elemento. Mapea a POST /api/mcp/logs-sync.

tronco_list_logs

Lista logs recientes con filtros date, from, to y limit opcionales. Mapea a GET /api/mcp/logs.

tronco_get_log

Busca un log por id. Mapea a GET /api/mcp/logs?id=... y no a un parámetro de ruta.

Descarga e instalación del skill compañero

El skill compañero le enseña a Codex a usar Tronco de forma segura: registrar explícitamente, sincronizar en masa, verificar resultados y cuidar los tokens. Lo sirve directamente esta app, así que no hace falta acceder al repositorio privado.

Descargar instalador Descargar instalador PowerShell 
curl -fsSL "https://troncoapp.cl/api/mcp/skill/install" | bash
Invoke-WebRequest "https://troncoapp.cl/api/mcp/skill/install?shell=powershell" -OutFile "$env:TEMP\troncoapp-agent-install.ps1"
& "$env:TEMP\troncoapp-agent-install.ps1"

El instalador copia el skill incluido en los directorios globales de Codex, Claude Code, OpenCode, Kiro, Gemini CLI, Cline y la ubicación portable .agents/skills, y también instala el servidor local en $HOME/.troncoapp. Sin argumentos, muestra un menú para seleccionar uno, varios o todos los agentes. También puedes usar --all o una selección individual; los directorios inexistentes se omiten. Usa --codex, --claude, --opencode, --kiro, --gemini, --cline, --agents o --path para un solo destino. --path es un destino personalizado explícito y se crea si hace falta. Mantén el token MCP en el entorno del cliente y configura el servidor MCP por separado en cada agente. Para Windows, usa el botón del instalador PowerShell de arriba.

Resumen de endpoints

Este es el mapa legible de la superficie MCP actual. El documento OpenAPI contiene los schemas y detalles de respuestas completos.

Endpoints de la API MCP de Tronco
Método Ruta Auth Uso
GET /api/mcp/docs Público Documentación OpenAPI para máquinas
GET /api/mcp/skill/install Público Descargar el instalador del skill compañero
POST /api/mcp Token Bearer Endpoint MCP remoto
POST /api/mcp/logs Bearer token Crear un log de actividad
POST /api/mcp/logs-sync Bearer token Sincronizar logs de actividad en masa
GET /api/mcp/logs Bearer token Listar logs de actividad
GET /api/mcp/logs?id=... Bearer token Obtener un log de actividad
GET /api/mcp/tokens Sesión Clerk Listar metadatos de tokens
POST /api/mcp/tokens Sesión Clerk Crear un token personal
DELETE /api/mcp/tokens/:id Sesión Clerk Revocar un token personal

Errores comunes y límites

Los errores son objetos JSON con success: false y un mensaje error. Revisa el código de estado antes de reintentar.

  • 400 — JSON, campos, fechas o parámetros inválidos, o un rango from/to incorrecto.
  • 401 — Falta el bearer token, es inválido o fue revocado; las rutas de tokens también devuelven esto sin sesión Clerk.
  • 404 — El log o token no existe en tu cuenta.
  • 409 — Una clave de idempotencia se reutilizó con otros datos, un elemento del lote entra en conflicto o la cuenta ya tiene 10 tokens activos.
  • 413 — El body de creación o sincronización masiva supera 1.000.000 de bytes.
  • 500 — Ocurrió un error inesperado del servidor; reintenta con cuidado.

Límites útiles

Ten en cuenta estas restricciones al construir tu integración:

  • Límite de lista: 1–100 resultados, con 20 por defecto; la sincronización masiva acepta 1–100 logs por llamada.
  • Contenido del log: 10–5000 caracteres.
  • Campo people: hasta 1000 caracteres.
  • Nombre del token: 1–80 caracteres; máximo 10 tokens activos por cuenta.
¿Necesitas el contrato completo para máquinas? Abre el enlace al JSON OpenAPI al inicio de esta página. Es la referencia canónica para las integraciones.