Referencia técnica: API MCP de AdminJR
Última actualización: 20/10/2026
Documentación para desarrolladores que integran asistentes de IA o automatizaciones propias contra la API de AdminJR. Si buscas la guía paso a paso para usuarios finales, consulta cómo conectar tu IA con MCP.
Autenticación
La API usa tokens personales de Laravel Sanctum, generados por cada usuario desde Integraciones IA dentro de su panel. Se envían como Bearer token en cada solicitud:
Authorization: Bearer <token>
Accept: application/json
Cada token tiene una fecha de vencimiento obligatoria (no existen tokens permanentes)
y puede revocarse en cualquier momento desde la interfaz; una vez revocado o vencido,
cualquier solicitud con ese token responde 401 Unauthorized.
Permisos (abilities)
Cada token tiene una de estas combinaciones de permisos, elegida al crearlo:
| Ability | Permite |
|---|---|
read:own | Leer cuentas, categorías y transacciones del usuario dueño del token. |
write:own | Crear transacciones a nombre del usuario dueño del token (siempre además de read:own). |
Una solicitud que requiere una ability que el token no tiene responde
403 Forbidden.
Aislamiento por usuario
Todas las operaciones se resuelven exclusivamente a partir del usuario dueño del token
autenticado — nunca de un identificador que envíes en la URL o el cuerpo de la solicitud.
Un token jamás puede leer ni escribir cuentas, categorías o transacciones de otro usuario:
si intentas usar un cuenta_id o categoria_id
que no te pertenece, la API responde 404 Not Found, como si no existiera.
Endpoints
/api/mcp/whoami
Requiere read:own. Devuelve el usuario dueño del token y las abilities/expiración del token actual. Útil para que un agente se autodescubra.
/api/mcp/cuentas
Requiere read:own. Devuelve todas las cuentas del usuario, con su saldo actual.
/api/mcp/categorias
Requiere read:own. Devuelve todas las categorías del usuario.
/api/mcp/transacciones
Requiere read:own. Lista las transacciones del usuario, más recientes primero.
Parámetros de query (todos opcionales):
cuenta_id— filtra por cuentacategoria_id— filtra por categoríadesde/hasta— rango de fechas (YYYY-MM-DD)limite— máximo de resultados (por defecto 100, tope 500)
/api/mcp/transacciones
Requiere write:own. Crea una transacción y actualiza el saldo de la cuenta.
Body JSON:
{
"cuenta_id": 7,
"categoria_id": 2,
"tipo": "ingreso",
"monto": 250.00,
"descripcion": "Depósito",
"fecha": "2026-08-16"
}
tipo debe ser uno de: ingreso, egreso, inversion, costo.
fecha es opcional (por defecto hoy). cuenta_id y categoria_id deben pertenecer al usuario dueño del token.
Códigos de respuesta comunes
| Código | Significado |
|---|---|
200 / 201 | Solicitud exitosa (201 al crear una transacción). |
401 | Token ausente, inválido, vencido o revocado. |
403 | El token no tiene la ability requerida (ej. token de solo lectura intentando escribir). |
404 | La cuenta o categoría indicada no existe o no pertenece al usuario del token. |
422 | Datos inválidos (ej. tipo no reconocido, saldo insuficiente). |
Ejemplo completo
curl -X POST https://tu-dominio.com/api/mcp/transacciones \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"cuenta_id": 7,
"categoria_id": 2,
"tipo": "egreso",
"monto": 80.50,
"descripcion": "Compra de prueba"
}'