Dos formas de conectarte

Cabgo expone dos modos para que tu cliente MCP (Claude Desktop, Cursor, Continue, etc.) se conecte:

A · Hosted — configurar tu agente

La forma más rápida. Tu cliente MCP descubre el servidor via su Server Card y completa el OAuth dinámicamente.

Claude Desktop (hosted)

{
  "mcpServers": {
    "cabgo": {
      "url": "https://www.cabgo.app/mcp"
    }
  }
}

Al primer uso te abrirá el navegador para autorizar (mismo flujo OAuth que usaría el paquete npm). Soporta operator (audience=dashboard), rider (audience=rider) y driver (audience=driver).

B · STDIO — instalación local

npm install -g cabgo-mcp
# o usa npx sin instalarlo globalmente:
npx cabgo-mcp@latest login

Login

La primera vez ejecuta cabgo-mcp login. El comando:

1. Registra un cliente OAuth dinámico (RFC 7591) en www.cabgo.app/oauth/register con PKCE.
2. Abre tu navegador a /oauth/authorize con un redirect loopback en 127.0.0.1:47821.
3. Tras tu consent, captura el code y lo intercambia por tokens.
4. Guarda los tokens en ~/.config/cabgo-mcp/tokens.json con permisos 0600.

Para autorizar como rider o driver en lugar de operador, pasa los scopes apropiados:

CABGO_DEFAULT_SCOPES="openid profile email rider.profile:read rider.trips:read rider.trips:create" \
  cabgo-mcp login

El consent screen rider/driver acepta inicio de sesión con Google sobre el dominio del tenant (si lo tiene configurado) con fallback a cabgo.app/oauth/{slug}/consent.

Configurar tu agente

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\\Claude\\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cabgo": {
      "command": "npx",
      "args": ["-y", "cabgo-mcp@latest", "serve"]
    }
  }
}

Reinicia Claude Desktop. Las tools de Cabgo aparecen bajo el ícono 🔌.

Cursor

Cmd-Shift-P → "Cursor Settings: Open MCP" → añade:

{
  "cabgo": {
    "command": "npx",
    "args": ["-y", "cabgo-mcp@latest", "serve"]
  }
}

Continue (VS Code / JetBrains)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "cabgo-mcp@latest", "serve"]
        }
      }
    ]
  }
}

Tools disponibles

La lista canónica vive en el OpenAPI document — cada operación es una tool con el mismo nombre prefijado por cabgo_. La referencia de la API renderiza todos los endpoints, scopes requeridos y permisos.

Resumen por audiencia:

• Operador — lectura — cabgo_list_trips, cabgo_get_trip, cabgo_list_drivers, cabgo_list_pending_drivers, cabgo_list_customers, cabgo_list_pending_customers, cabgo_get_settings, cabgo_list_zones, cabgo_list_services, cabgo_list_businesses, cabgo_list_orders, cabgo_wallet_totals, cabgo_get_branding, cabgo_reports_summary, cabgo_report_by_driver, cabgo_report_by_zone, cabgo_fare_breakdown, cabgo_cash_remittance_pending, cabgo_list_builds, cabgo_get_build, cabgo_list_business_products, cabgo_list_channels, cabgo_list_whatsapp_templates, cabgo_list_conversational_flows, cabgo_list_coupons, cabgo_list_b2b_vouchers, cabgo_fiscal_report.
• Operador — escritura (moderación + lifecycle) — cabgo_approve_driver, cabgo_reject_driver, cabgo_bulk_activate_drivers, cabgo_bulk_deactivate_drivers, cabgo_approve_customer, cabgo_bulk_deactivate_customers, cabgo_update_branding, cabgo_update_business, cabgo_create_business_product, cabgo_create_channel, cabgo_create_coupon, cabgo_create_b2b_voucher, cabgo_trigger_build.
• Operador — presets — cabgo_list_presets, cabgo_apply_preset (devuelve un plan; el agente ejecuta paso a paso).
• Rider — cabgo_me, cabgo_my_trips, cabgo_request_ride, cabgo_cancel_my_trip, cabgo_list_addresses, cabgo_save_address, cabgo_my_wallet, cabgo_list_payment_methods, cabgo_my_orders.
• Driver — cabgo_me, cabgo_my_trips, cabgo_set_driver_status, cabgo_accept_trip, cabgo_mark_arrived, cabgo_start_trip, cabgo_complete_trip, cabgo_my_wallet.

Safety tiers (T1-T4)

Las herramientas de escritura se agrupan en cuatro niveles según su impacto. Esto está implementado en src/lib/mcp/safety.ts y aplica a TODA mutación tenant-scoped:

• T1 — Lectura: idempotente. Sin confirmación. (cabgo_list_*, cabgo_get_*,cabgo_*_status.)
• T2 — Mutación tenant-only reversible: la confirmación nativa de ChatGPT (muestra los args antes de llamar) es suficiente. Ejemplo: aprobar conductor, crear cupón, actualizar branding, PATCH driver/customer.
• T3 — Visible a usuarios finales: dryRun: true por default → devuelve preview + confirmationToken. El agente debe pasar dryRun: false explícito en una segunda llamada para ejecutar. Toda ejecución T3 se loguea como mcp_audit en Vercel. Ejemplos: cabgo_promote_build, cabgo_publish_to_play, cabgo_attach_custom_domain, cabgo_send_whatsapp_template, cabgo_set_surge, cabgo_admin_cancel_trip, cabgo_firebase_onboard.
• T4 — Irreversible / financiero: dos pasos. Primer llamado dryRun:true → mint un confirmationToken firmado con HMAC, ligado al tenant + acción + hash del payload, con TTL de 5 min. El segundo llamado debe pasar el token y un payload idéntico — si cambia cualquier campo, el token se invalida. Ejemplos: cabgo_detach_custom_domain, cabgo_adjust_driver_wallet.

Los tokens son stateless (HMAC-SHA256 sobre la representación canónica del payload). Cambiar key order en el JSON no invalida el token — pero cambiar un valor sí.

Aislamiento por tenant

Cada token de operador se emite con un único tenantId (la company del usuario que autorizó el flujo OAuth). En el backend, cada ruta de /api/v1/* resuelve al actor con authorizeRequest() y fija companyId = actor.tenantId en todos los where de Prisma:

• Reads (lista / get) — findMany / findFirst incluyen companyId: actor.tenantId. IDs de otra company devuelven 404 not_found aunque sean válidos.
• Writes (mutaciones) — el orquestrador (triggerCompanyBuild, update de drivers/customers, etc.) recibe companyId del actor y valida ownership server-side. Un agente no puede pasar el id de otra company por payload.
• Multi-tenant fan-out (SUPER_ADMIN). Cuando un usuario es admin de varias companies, el consent screen muestra el picker; el token resultante apunta a la company elegida. Para operar otra company, repetir el flow.

Variables de entorno

Resolución de problemas

• not logged in — ejecuta cabgo-mcp login.
• refresh failed: 401 invalid_grant — el refresh token fue revocado (lo borraste desde el dashboard o el tenant fue desactivado). Corre cabgo-mcp logout && cabgo-mcp login.
• 403 feature_disabled — el operador apagó la feature requerida (delivery, scheduled trips, etc). Verifica con cabgo_get_settings.
• 403 insufficient_scope — el token se emitió con menos scopes de los que la tool necesita. Re-login pasando los scopes extras.

Referencias

• API v1 reference + scope catalog
• OpenAPI 3.1 spec
• OAuth 2.0 authorization server metadata
• Source en GitHub