Servidor MCP de Treli

Conecta tu cuenta de Treli con asistentes de IA como Claude, ChatGPT o Cursor y trabaja con tus datos en lenguaje natural: consulta clientes y suscripciones, revisa cobros y pagos rechazados, mira tus métricas y configura tu catálogo.

El servidor usa el Model Context Protocol (MCP), un estándar abierto para que las aplicaciones de IA se conecten a herramientas externas.

URL DEL SERVIDOR
https://api.treli.co/mcp

Qué puedes hacer

Algunos ejemplos de lo que puedes pedirle a tu asistente una vez conectado:

"Busca al cliente con correo ana@ejemplo.com y muéstrame sus suscripciones y sus últimos tres cobros."

"Lista las transacciones rechazadas de esta semana y agrúpalas por motivo de rechazo."

"¿Qué cobros están vencidos ahora mismo y cuánto suman?"

"Compara el MRR y el churn de este mes con los del mes pasado."

"Crea un producto llamado Plan Pro con un precio mensual de 120.000 COP y dame un enlace de pago."

"Crea un cupón del 15% llamado BLACK15, de un solo uso, que venza el 30 de noviembre."

Requisitos

Una cuenta activa de Treli.

Un usuario con rol Super admin, Admin o Desarrollador. Los demás roles no pueden conectar aplicaciones.

Para crear y editar necesitas un plan con acceso completo a la API. En los planes con acceso de solo lectura a la API, la conexión también es de solo lectura.

Las métricas de suscripciones requieren la función de analítica avanzada de tu plan.

Cómo conectarte

Claude

Abre Configuración → Conectores y elige Agregar conector personalizado.

Pega la URL del servidor: https://api.treli.co/mcp.

Haz clic en Conectar. Se abrirá Treli para que inicies sesión y autorices el acceso.

Claude Code

Luego ejecuta /mcp dentro de Claude Code para iniciar sesión.

Otros clientes

Cualquier cliente compatible con servidores MCP remotos (ChatGPT, Cursor, VS Code y otros) puede conectarse: agrega un servidor MCP remoto con la URL https://api.treli.co/mcp. El cliente descubre solo el resto de la configuración y abre la pantalla de autorización de Treli.

También encuentras la URL en tu dashboard, en Configuraciones → Desarrolladores → Apps conectadas.

Autorizar el acceso

Al conectar, Treli te pide iniciar sesión (con tu verificación en dos pasos, si la tienes activa) y te muestra una pantalla de autorización. En ella decides:

Opción	Qué significa
Ver información	Siempre incluido. El asistente puede consultar tus datos.
Crear y editar	Opcional. Desmárcalo si solo quieres una conexión de lectura.
Datos reales o datos de prueba	La conexión trabaja en un solo modo. Para usar el otro, conecta de nuevo.

La pantalla también muestra a dónde se entregará el acceso. Autoriza solo si tú iniciaste la conexión y reconoces esa dirección: cualquier aplicación puede elegir el nombre con el que se presenta, pero no la dirección que recibe el acceso.

La conexión actúa con los permisos de tu usuario. Nunca puede hacer más de lo que tú puedes hacer en el dashboard.

Qué puede y qué no puede hacer

Puede consultar: clientes, suscripciones, cobros, facturas, transacciones, productos, precios, cupones, enlaces de pago, tiendas y métricas.

Puede crear y editar (si lo autorizaste): clientes, productos, precios, cupones, enlaces de pago y tiendas. También puede agregar notas y etiquetas a suscripciones, y etiquetas a cobros.

No puede, en ningún caso:

Cobrar, reembolsar o anular pagos.

Crear, cancelar, pausar o reanudar suscripciones.

Modificar los montos de suscripciones o cobros existentes.

Cambiar configuraciones, usuarios, claves API o pasarelas de pago.

Esas acciones siguen disponibles en el dashboard y en la API REST.

Herramientas disponibles

El servidor expone 41 herramientas: 26 de consulta y 15 de escritura.

Área	Consulta	Escritura
Clientes	`list_customers`, `get_customer`, `list_customer_payment_methods`	`create_customer`, `update_customer`
Suscripciones	`list_subscriptions`, `get_subscription`, `list_subscription_notes`	`add_subscription_note`, `tag_subscription`
Cobros	`list_collections`, `get_collection`	`tag_collection`
Facturas	`list_invoices`, `get_invoice`	—
Transacciones	`list_transactions`, `get_transaction`	—
Productos	`list_products`, `get_product`	`create_product`, `update_product`
Precios	`list_prices`, `get_price`	`create_price`, `update_price`
Cupones	`list_coupons`, `get_coupon`	`create_coupon`, `update_coupon`
Enlaces de pago	`list_payment_links`, `get_payment_link`	`create_payment_link`, `update_payment_link`
Tiendas	`list_storefronts`, `get_storefront`	`create_storefront`, `update_storefront`
Métricas	`get_subscription_metrics`, `get_collection_metrics`, `get_payment_metrics`, `get_paid_today_by_hour`	—

Cada herramienta corresponde a un endpoint de la API REST y aplica las mismas validaciones y reglas. Los parámetros y las respuestas usan los mismos nombres de campo que la API.

Si la conexión es de solo lectura (porque así la autorizaste o por tu plan), las herramientas de escritura no aparecen en la lista.

Paginación

Las herramientas de listado devuelven has_more y next_cursor. Para obtener la página siguiente, el asistente repite la llamada con start_after igual a next_cursor. Para volver atrás, usa start_before con previous_cursor. El tamaño de página se controla con limit (máximo 100; 200 en suscripciones y cobros).

La excepción es list_transactions, que se pagina con page y devuelve el total de páginas en pagination.

Formatos

IDs: llevan prefijo según el recurso, por ejemplo cus_ (cliente), sub_ (suscripción), col_ (cobro).

Fechas: YYYY-MM-DD HH:MM:SS en la zona horaria de tu cuenta. Los filtros de list_transactions y las métricas usan YYYY-MM-DD.

Montos: se devuelven como texto con dos decimales, por ejemplo "20000.00", junto con su moneda.

Errores

Cuando una herramienta falla, la respuesta incluye el mismo objeto de error que la API REST:

{
  "error": {
    "code": "resource_missing",
    "message": "El cliente no existe: cus_123",
    "type": "invalid_request_error"
  }
}

Código	Causa
`resource_missing`	El recurso (o el cursor de paginación) no existe en tu cuenta o en el modo de la conexión.
`invalid_parameter`	Un parámetro no pasó la validación. El campo `param` indica cuál.
`invalid_action`	La acción no es válida en el estado actual, por ejemplo crear un cliente con un correo que ya existe.
`access_denied`	Tu rol no tiene permiso para esa acción.
`entitlement_required`	Tu plan no incluye esa función, por ejemplo escritura por API o analítica avanzada.

Gestionar y revocar conexiones

En Configuraciones → Desarrolladores → Apps conectadas ves cada aplicación que conectaste con tu usuario: sus permisos, si usa datos reales o de prueba, cuándo la conectaste, su último uso y cuándo vence. Desde ahí puedes revocar el acceso en cualquier momento; el efecto es inmediato.

Una conexión deja de funcionar cuando:

La revocas.

Pasan 90 días desde que la autorizaste. Después de eso, el asistente te pedirá autorizar de nuevo.

Pasa 30 días sin uso.

Cambias tu contraseña o tu usuario se desactiva.

Tu rol deja de ser Super admin, Admin o Desarrollador.

Cerrar sesión en el dashboard no desconecta tus aplicaciones.

Las acciones de escritura que hace un asistente quedan en Desarrolladores → Registros, con origen mcp y tu usuario, igual que cualquier otra llamada a la API.

Recomendaciones de seguridad

Autoriza solo lo necesario. Si solo quieres reportes y consultas, desmarca "Crear y editar".

Prueba primero con datos de prueba antes de dar acceso a tus datos reales.

Revisa antes de confirmar. La mayoría de los asistentes te piden confirmar las acciones de escritura. Lee lo que van a crear o cambiar, sobre todo precios y cupones.

Ten presente de dónde viene el texto. Los nombres, notas y otros campos de tus clientes son texto escrito por terceros. Si un asistente propone una acción que no pediste después de leer esos datos, no la confirmes.

Revoca lo que ya no uses y las conexiones de equipos que ya no tengas.

No compartas la conexión. Cada persona de tu equipo debe conectar su propio usuario.

Referencia técnica

Esta sección es para quienes desarrollan un cliente MCP o quieren integrar el servidor directamente.

Transporte


Endpoint	`POST https://api.treli.co/mcp`
Transporte	Streamable HTTP, sin estado
Formato	Un mensaje JSON-RPC 2.0 por solicitud, o un lote de hasta 20 con una sola llamada `tools/call`
Respuesta	`application/json`. El servidor no abre flujos SSE; `GET` y `DELETE` responden `405`
Capacidades	`tools`
Versiones del protocolo	`2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`

Una solicitud sin credenciales válidas recibe 401 con la cabecera WWW-Authenticate: Bearer resource_metadata="https://api.treli.co/.well-known/oauth-protected-resource".

Autenticación

El servidor usa OAuth 2.1 con código de autorización y PKCE. Solo admite clientes públicos.

Documento o endpoint	URL
Metadatos del recurso protegido (RFC 9728)	`https://api.treli.co/.well-known/oauth-protected-resource`
Metadatos del servidor de autorización (RFC 8414)	`https://api.treli.co/.well-known/oauth-authorization-server`
Registro dinámico de clientes (RFC 7591)	`POST https://api.treli.co/oauth/register`
Autorización	`https://dashboard.treli.co/oauth/authorize`
Token	`POST https://api.treli.co/oauth/token`
Revocación (RFC 7009)	`POST https://api.treli.co/oauth/revoke`

El endpoint de autorización es la pantalla de autorización del dashboard. Toma siempre las URLs de los metadatos en lugar de fijarlas en tu código.

Parámetro	Valor
Tipos de concesión	`authorization_code`, `refresh_token`
PKCE	Obligatorio, solo `S256`
Autenticación del cliente	Ninguna (`token_endpoint_auth_method: none`)
Scopes	`read`, `write`. `write` incluye `read`. Si no envías `scope`, se solicitan ambos
Indicador de recurso (RFC 8707)	`https://api.treli.co/mcp`
URIs de redirección	`https`, `http` solo en loopback (el puerto puede variar), o un esquema propio de la aplicación

Tokens

Token	Vigencia	Notas
Código de autorización	5 minutos	De un solo uso
Token de acceso	1 hora	Se envía como `Authorization: Bearer`
Token de actualización	30 días sin uso	Rota en cada uso: cada respuesta trae uno nuevo y el anterior deja de servir
Autorización completa	90 días	Ningún token dura más que la autorización

Reutilizar un token de actualización que ya rotó revoca la autorización completa. Guarda siempre el token nuevo que devuelve cada renovación y evita renovar en paralelo.

Cuando la autorización vence o se revoca, el endpoint de token responde invalid_grant. En ese caso, inicia de nuevo el flujo de autorización.

Ejemplo

Listar las herramientas disponibles:

Llamar a una herramienta:

La respuesta trae el resultado en result.content[0].text como JSON, y result.isError indica si la herramienta falló.

Preguntas frecuentes

¿Es lo mismo que usar una clave API?
No. Una clave API da acceso a toda la cuenta y no vence. Una conexión MCP está ligada a tu usuario y a tus permisos, vence, se limita al modo que elegiste y no puede ejecutar acciones de cobro.

¿Puedo tener varias conexiones?
Sí. Puedes conectar varios asistentes, y el mismo asistente en modo de prueba y con datos reales. Cada una aparece por separado en Apps conectadas.

Mi asistente dejó de funcionar. ¿Qué hago?
Lo más probable es que la autorización venció, se revocó o tu rol cambió. Vuelve a conectar el servidor desde tu asistente y autoriza de nuevo.

No veo las herramientas para crear o editar.
La conexión es de solo lectura: o no marcaste "Crear y editar" al autorizar, o tu plan solo incluye acceso de lectura a la API. En el primer caso, conecta de nuevo y márcalo.

¿El asistente ve los datos de las tarjetas de mis clientes?
No. Los métodos de pago se devuelven enmascarados, igual que en la API.

MCP

Servidor MCP de Treli#

Qué puedes hacer#

Requisitos#

Cómo conectarte#

Claude#

Claude Code#

Otros clientes#

Autorizar el acceso#

Qué puede y qué no puede hacer#

Herramientas disponibles#

Paginación#

Formatos#

Errores#

Gestionar y revocar conexiones#

Recomendaciones de seguridad#

Referencia técnica#

Transporte#

Autenticación#

Tokens#

Ejemplo#

Preguntas frecuentes#