Crea agenti più sicuri con la documentazione Flowtly MCP

Come rimanere aggiornato

1. Esegui il comando di sincronizzazione dopo ogni aggiornamento MCP.
2. Riavvia lo stack degli agenti per recepire le modifiche alle funzionalità.
3. Aggiungi questa pagina ai segnalibri per le ultime indicazioni su Flowtly MCP.

Cosa è incluso

• Regole di autenticazione, CORS e caching per gli endpoint MCP.
• 19 namespace di risorse con operazioni di elenco, lettura e scrittura.
• 8 agenti integrati con controllo degli accessi basato su ruolo.
• 14 riepiloghi logici per analisi calcolate.
• Payload JSON-RPC, esempi di codice e suggerimenti per l'integrazione.

Avvio rapido

• Passaggio 1 — Ottieni un token: Vai su Flowtly Workspace → Token agente e genera un token client.
• Passaggio 2 — Inizializza: POST su https://mcp.flowtly.eu/mcp con {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Passaggio 3 — Leggi i dati: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Passaggio 4 — Scrivi i dati: 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\"}"}]}}
• Tutte le richieste usano Authorization: Bearer <YOUR_TOKEN> e Content-Type: application/json.

Trasporto e autenticazione

• URL base (prod): https://mcp.flowtly.eu
• Endpoint: POST /mcp (entry JSON-RPC), GET /health (controllo liveness)
• Autenticazione: Authorization: Bearer <token> (preferito). Fallback: variabile d'ambiente FLOWTLY_API_KEY. Generazione token: workspace.flowtly.eu/user/agent-tokens
• Content-Type: application/json. Body: JSON-RPC 2.0 {"jsonrpc":"2.0","id":"...","method":"...","params":{...}}
• CORS: Credenziali consentite solo da https://workspace.flowtly.eu. Non combinare mai Access-Control-Allow-Origin: * con Access-Control-Allow-Credentials: true.
• API upstream: https://api.flowtly.eu — il server MCP inoltra tutte le richieste all'API REST di Flowtly.

initialize

• Negozia la versione del protocollo, le funzionalità e i namespace disponibili.
• Richiesta: {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Funzionalità di risposta: {"resources":{"list":true,"read":true,"write":true}}
• Namespace disponibili: 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

• Metodo: resources/{namespace}/list — namespace predefinito: work-times se omesso.
• Namespace (19): work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests, candidate-notes, resource-request-candidates.
• Restituisce un array di oggetti {uri, name} che descrivono le risorse disponibili per namespace. Vedi il dettaglio dei namespace qui sotto per maggiori informazioni.
• Esempio: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Metodo: resources/{namespace}/read — namespace predefinito: work-times.
• Parametri: uri (obbligatorio) — l'URI della risorsa, ad es. /api/work-times.
• allowPrefixes: abilita le corrispondenze cross-namespace. Qualsiasi URI che inizia con un prefisso consentito viene accettato.
• Risoluzione {current}: {current} nei parametri di query del dipendente si risolve automaticamente in /api/employees/me.
• Default automatici: work-times aggiunge date[after]/date[before] (ultimi 30 giorni), employees aggiunge itemsPerPage=200, holidays/vacations aggiungono default di paginazione.
• Arricchimento: Responsibilities read segue fino a 10 link @id per arricchire i campi titolo/nome.
• Namespace logico: restituisce riepiloghi calcolati lato server anziché payload API grezzi.
• Risposta: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Metodo: resources/{namespace}/write — solo le risorse con allowWrite accettano scritture.
• Routing: POST per la creazione, PATCH (con application/merge-patch+json) quando l'URI termina con un ID. Override tramite params.contentType.
• Percorsi di creazione: /api/.../create forza POST anche se è presente un ID.
• Convenzione IRI: params.uri usa percorsi /api/..., ma i riferimenti alle entità all'interno dei payload JSON devono usare gli IRI upstream (es. "project": "/projects/1", non "/api/projects/1").
• Namespace scrivibili: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Helper di scrittura logica: resources/logical/write supporta /logical/work-times/log (POST su /api/work-times), /logical/recruiting/resource-requests/update?id=<id> e /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Agenti integrati

• EmployeeAgent (employee): Operazioni quotidiane — registra il tempo di lavoro, controlla le ferie, visualizza le assegnazioni. Accesso: qualsiasi utente autenticato (limitato per token/istanza).
• ManagerAgent (manager): Supporto al project/eng manager — tariffe, organico, costi, approvazioni. Richiede: ruolo project_manager o admin.
• ExecutiveAgent (executive): Snapshot per la leadership — KPI, budget, rollup, approvazioni. Richiede: ruolo admin, executive, director, vp o c-level.
• HRManagerAgent (hr): HR e assenze — saldi ferie, storico assenze, festività del team. Accesso: qualsiasi utente autenticato.
• AccountancyAgent (accountancy): Query finanziarie — elenca le transazioni, riepiloga gli importi. Non espone mai gli URL degli allegati. Accesso: qualsiasi utente autenticato.
• RecruiterAgent (recruiter): Recruiting — elenca i ruoli aperti, cerca/crea candidati, collegali ai ruoli, aggiungi note. Richiede: ruolo candidates_manager, admin o recruiter.
• OnboardingAgent (onboarding): Guida per i nuovi utenti — aiuto alla configurazione, navigazione, risposte a "dove trovo X". Accesso: qualsiasi utente autenticato.
• TechAgent (tech): Configurazione tecnica — richieste di credenziali MCP/ChatGPT. Genera credenziali client per utente dopo l'approvazione dell'amministratore. Accesso: aperto a tutti i ruoli (sarà ristretto in futuro).
• Selezione agente: Usa employee per compiti personali; hr per assenze/ferie; manager per organico/costi; executive per KPI; accountancy per la finanza; recruiter per i candidati; onboarding per la configurazione.
• Modello di accesso: I controlli sui ruoli usano ruoli/autorità/permessi di Flowtly. Gli agenti ristretti rifiutano le azioni quando non è presente alcun ruolo richiesto corrispondente. Tutti gli agenti usano esclusivamente lo strumento MCP API — nessun servizio esterno.

Namespace logico — riepiloghi calcolati

• Riepiloghi work-time: /logical/work-times/summary — ore aggregate per dipendente/progetto. Supporta date[after]/date[before] (default ultimi 7 giorni).
• Riepilogo dipendenti: /logical/employees/summary — organico, reparti e panoramica degli stati.
• Riepilogo progetti: /logical/projects/summary — progetti attivi, tipi di fatturazione e distribuzione clienti.
• Work-time dipendenti: /logical/employee-work-times/summary — dettaglio dell'utilizzo per dipendente.
• Tariffe progetto: /logical/project-rates/summary — schede tariffe e panoramica delle tariffe di fatturazione.
• Transazioni: /logical/transactions/summary — totali delle spese, categorizzazione e tendenze.
• Redditività progetto: /logical/project-profitability/summary — ricavi vs costi per progetto.
• Gruppi budget: /logical/budget-groups/summary — allocazioni dei gruppi budget e stato del consumo.
• Budget: /logical/budgets/summary — utilizzo del budget individuale e avvisi.
• Onboarding aziendale: /logical/company-onboarding/status — avanzamento della configurazione del workspace e passaggi in attesa.
• Ruoli aperti: /logical/recruiting/open-roles — richieste di risorse non soddisfatte e pipeline di assunzione.
• Candidati: /logical/recruiting/candidates — distribuzione delle fasi della pipeline candidati.
• Festività: /logical/holidays — dati aggregati sulle assenze e disponibilità del team.
• Log work-time (scrittura): /logical/work-times/log — POST crea una voce di tempo tramite /api/work-times.

Caching e performance

• Cache logica Redis: Cache opzionale per le letture logiche. Può condividere Redis con l'API principale per i pattern di invalidazione.
• Variabili d'ambiente: MCP_LOGICAL_CACHE_ENABLED (abilitata automaticamente quando esiste l'URL Redis), MCP_LOGICAL_CACHE_REDIS_URL (fallback: REDIS_URL, CACHE_REDIS_URL).
• Formato chiave: Prefisso mcp:logical:v1: — delimitato per istanza e principal, include l'URI logico normalizzato. Configura il prefisso tramite MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 secondi (24 ore). Configurabile tramite MCP_LOGICAL_CACHE_TTL_SECONDS.

Gestione degli errori

• Errore JSON-RPC standard: {"jsonrpc":"2.0","id":"...","error":{"code":-32000,"message":"Upstream Flowtly API failed","data":{"status":502}}}
• Codici di errore comuni: -32700 (errore di parsing), -32600 (richiesta non valida), -32601 (metodo non trovato), -32000 (errore API upstream).
• Il campo data.status rispecchia il codice di stato HTTP dell'API Flowtly upstream quando disponibile.

Note aggiuntive

• allowPrefixes: Permette a resources/read di accettare URI che iniziano con prefissi consentiti, abilitando ricerche cross-namespace.
• Riferimento OpenAPI: Disponibile in public/mcp/openapi.json (copiato in dist/mcp/openapi.json durante la build).
• Contratti di intent LLM: Schemi router e manager documentati in docs/llm-intent-architecture.md, implementati in packages/agent/src/intents/contract.ts.
• Paginazione: I valori predefiniti vengono applicati automaticamente per namespace. Sostituisci con parametri di query espliciti quando necessario.

Riferimento namespace — resources/list per namespace