Crea agentes más seguros con la documentación Flowtly MCP

Cómo mantenerte al día

1. Ejecuta el comando de sincronización después de cada actualización de MCP.
2. Reinicia tu stack de agentes para aplicar los cambios de capacidades.
3. Guarda esta página para consultar las últimas indicaciones de MCP.

Qué incluye

• Reglas de autenticación y claves API para endpoints MCP.
• Esquemas de recursos para base de conocimiento, blog, notas de versión, inversores y actualizaciones de producto.
• Payloads JSON-RPC y consejos de lectura/escritura para agentes.
• 14 resúmenes lógicos para análisis computarizados.
• Cargas útiles JSON-RPC, ejemplos de código y consejos de integración.

Inicio rápido

• Paso 1 — Obtener un token: Navegue a Flowtly Workspace → Agent Tokens y genere un token de cliente.
• Paso 2 — Inicializar: POST a https://mcp.flowtly.eu/mcp con {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Paso 3 — Leer datos: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Paso 4 — Escribir datos: POST {"jsonrpc":"2.0","id":"write-1","method":"resources/work-times/write","params":{"uri":"/api/work-times","contents":[{"text":"{\"date\":\"2026-04-03\",\"seconds\":3600,\"project\":\"/projects/1\",\"description\":\"Support\"}"}]}}
• Todas las solicitudes usan Authorization: Bearer <YOUR_TOKEN> y Content-Type: application/json.

Transport & Auth

• Endpoints: POST /mcp (entrada JSON-RPC), GET /health (liveness), POST /api/chat (proxy de consola; requiere Authorization: Bearer )
• Headers: Authorization Bearer token (preferido; si no, FLOWTLY_API_KEY), el header instance es opcional y se reenvía
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Credenciales permitidas solo desde https://workspace.flowtly.eu. Nunca combine Access-Control-Allow-Origin: * con Access-Control-Allow-Credentials: true.
• API ascendente: https://api.flowtly.eu — el servidor MCP proxy todas las solicitudes a la API REST de Flowtly.

initialize

• Negocia capacidades y namespaces.
• Ejemplo de params: { "protocolVersion": "2024-11-05" }
• Devuelve capacidades (list, read, write) y namespaces (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Espacios de nombres disponibles: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.

resources/list

• Método: resources/{namespace}/list (namespace por defecto: work-times si se omite)
• Namespaces: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Devuelve URIs por namespace (ver detalle abajo).
• Ejemplo: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Método: resources/{namespace}/read (namespace por defecto: work-times).
• Parámetros incluyen uri, p. ej. /api/work-times
• allowPrefixes habilita coincidencias entre namespaces; {current} se resuelve a /api/employees/me.
• Algunos recursos añaden valores por defecto (work-times añade límites de fecha; employees añade itemsPerPage; holidays/vacations añaden paginación por defecto).
• Responsibilities sigue hasta 10 enlaces @id para enriquecer título/nombre.
• El namespace logical devuelve resúmenes del servidor en lugar de payloads brutos.
• Devuelve el payload contents de la API Flowtly subyacente.
• Respuesta: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Solo recursos con allowWrite aceptan escrituras; POST salvo que la URI termine en id (entonces PATCH con application/merge-patch+json).
• /api/.../create fuerza POST aunque exista id; se puede forzar el tipo con params.contentType.
• Helper de escritura lógica: resources/logical/write soporta /logical/recruiting/resource-requests/update?id= y /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• Convención IRI: params.uri usa rutas /api/..., pero las referencias de entidad dentro de las cargas útiles JSON deben usar IRIs ascendentes (por ejemplo, "project": "/projects/1", no "/api/projects/1").
• Espacios de nombres escribibles: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Ayudantes de escritura lógica: resources/logical/write soporta /logical/work-times/log (POST a /api/work-times), /logical/recruiting/resource-requests/update?id=<id> y /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Agentes integrados

• EmployeeAgent (employee): Operaciones diarias — registrar tiempo de trabajo, verificar vacaciones, ver asignaciones. Acceso: cualquier usuario autenticado (con ámbito por token/instancia).
• ManagerAgent (manager): Soporte para gerentes de proyecto/ingeniería — tarifas, personal, costos, aprobaciones. Requiere: rol de project_manager o admin.
• ExecutiveAgent (executive): Vistas generales de liderazgo — KPIs, presupuestos, resúmenes, aprobaciones. Requiere: rol de admin, executive, director, vp o c-level.
• HRManagerAgent (hr): RRHH y ausencias — saldos de vacaciones, historial de ausencias, festivos del equipo. Acceso: cualquier usuario autenticado.
• AccountancyAgent (accountancy): Consultas de finanzas — listar transacciones, resumir importes. Nunca muestra URLs de adjuntos. Acceso: cualquier usuario autenticado.
• RecruiterAgent (recruiter): Reclutamiento — listar roles abiertos, buscar/crear candidatos, adjuntar a roles, añadir notas. Requiere: rol de candidates_manager, admin o recruiter.
• OnboardingAgent (onboarding): Guía para nuevos usuarios — ayuda de configuración, navegación, respuestas a "dónde encontrar X". Acceso: cualquier usuario autenticado.
• TechAgent (tech): Configuración técnica — solicitudes de credenciales de MCP/ChatGPT. Genera credenciales de cliente por usuario después de la aprobación del administrador. Acceso: abierto a todos los roles (se restringirá).
• Selección de agente: Use employee para tareas personales; hr para ausencias/vacaciones; manager para personal/costos; executive para KPIs; accountancy para finanzas; recruiter para candidatos; onboarding para configuración.
• Modelo de acceso: Las comprobaciones de roles usan roles/autoridades/permisos de Flowtly. Los agentes restringidos rechazan acciones cuando no coincide ningún rol requerido. Todos los agentes usan solo la herramienta MCP API, sin servicios externos.

Namespace logical (/logical/*)

• Resúmenes de solo lectura: work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Resúmenes de recruiting: company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Resúmenes de holidays: logical/holidays.
• Ejemplo: /logical/work-times/summary admite date[after]/date[before] (por defecto últimos 7 días).
• Tarifas de proyecto: /logical/project-rates/summary — tarjetas de tarifas y resumen de tarifas de facturación.
• Transacciones: /logical/transactions/summary — totales de gasto, categorización y tendencias.
• Rentabilidad del proyecto: /logical/project-profitability/summary — ingresos vs costo por proyecto.
• Grupos de presupuesto: /logical/budget-groups/summary — asignaciones de grupos de presupuesto y estado de consumo.
• Presupuestos: /logical/budgets/summary — utilización de presupuesto individual y alertas.
• Incorporación de empresa: /logical/company-onboarding/status — progreso de configuración del espacio de trabajo y pasos pendientes.
• Roles abiertos: /logical/recruiting/open-roles — solicitudes de recursos no cubiertas y proceso de contratación.
• Candidatos: /logical/recruiting/candidates — distribución de las etapas del proceso de candidatos.
• Días festivos: /logical/holidays — datos de ausencias agregados y disponibilidad del equipo.
• Registro de tiempo de trabajo (escritura): /logical/work-times/log — POST crea una entrada de tiempo de trabajo a través de /api/work-times.

Caché y rendimiento

• Caché lógico de Redis: Caché opcional para lecturas lógicas. Puede compartir Redis con la API principal para patrones de invalidación.
• Variables de entorno: MCP_LOGICAL_CACHE_ENABLED (habilitado automáticamente cuando existe una URL de Redis), MCP_LOGICAL_CACHE_REDIS_URL (alternativas: REDIS_URL, CACHE_REDIS_URL).
• Formato de clave: Prefijo mcp:logical:v1: — con ámbito por instancia + principal, incluye URI lógico normalizado. Configure el prefijo mediante MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 segundos (24 horas). Configure mediante MCP_LOGICAL_CACHE_TTL_SECONDS.

Forma de error

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Códigos de error comunes: -32700 (error de análisis), -32600 (solicitud inválida), -32601 (método no encontrado), -32000 (fallo de la API superior).
• El campo data.status refleja el código de estado HTTP de la API superior de Flowtly cuando está disponible.

Notas

• allowPrefixes permite que resources/read acepte URIs que empiecen con prefijos permitidos.
• Referencia tipo OpenAPI disponible en public/mcp/openapi.json.
• Contratos de intención LLM: Patrones de enrutador + gestor documentados en docs/llm-intent-architecture.md, implementados en packages/agent/src/intents/contract.ts.
• Paginación: Los valores predeterminados se aplican automáticamente por espacio de nombres. Anule con parámetros de consulta explícitos cuando sea necesario.

resources/list por namespace