Bouw veiligere agents met Flowtly MCP documentatie

Hoe u actueel blijft

1. Voer de synchronisatieopdracht uit nadat MCP-updates zijn uitgebracht.
2. Herstart uw agent-stack om capaciteitswijzigingen op te halen.
3. Sla deze pagina op als bladwijzer voor de laatste Flowtly MCP-richtlijnen.

Wat is er inbegrepen

• Authenticatie-, CORS- en cachingregels voor MCP-endpoints.
• 19 resource-naamruimten met lijst-, lees- en schrijfbewerkingen.
• 8 ingebouwde agents met op rollen gebaseerde toegangscontrole.
• 14 logische samenvattingen voor berekende analyses.
• JSON-RPC-payloads, codevoorbeelden en integratietips.

Snelstart

• Stap 1 — Token ophalen: Ga naar Flowtly Workspace → Agent-tokens en genereer een clienttoken.
• Stap 2 — Initialiseren: POST naar https://mcp.flowtly.eu/mcp met {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Stap 3 — Gegevens lezen: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Stap 4 — Gegevens schrijven: 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\"}"}]}}
• Alle verzoeken gebruiken Authorization: Bearer <YOUR_TOKEN> en Content-Type: application/json.

Transport & authenticatie

• Basis-URL (productie): https://mcp.flowtly.eu
• Endpoints: POST /mcp (JSON-RPC-ingang), GET /health (levendheidscontrole)
• Authenticatie: Authorization: Bearer <token> (aanbevolen). Fallback: omgevingsvariabele FLOWTLY_API_KEY. Token genereren: workspace.flowtly.eu/user/agent-tokens
• Content-Type: application/json. Body: JSON-RPC 2.0 {"jsonrpc":"2.0","id":"...","method":"...","params":{...}}
• CORS: Inloggegevens alleen toegestaan van https://workspace.flowtly.eu. Combineer nooit Access-Control-Allow-Origin: * met Access-Control-Allow-Credentials: true.
• Upstream API: https://api.flowtly.eu — de MCP-server proxyt alle verzoeken naar de Flowtly REST API.

initialize

• Onderhandelt protocolversie, capaciteiten en beschikbare naamruimten.
• Verzoek: {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Reactiecapaciteiten: {"resources":{"list":true,"read":true,"write":true}}
• Beschikbare naamruimten: 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

• Methode: resources/{namespace}/list — standaard naamruimte: work-times als weggelaten.
• Naamruimten (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.
• Retourneert een array van {uri, name}-objecten die beschikbare resources per naamruimte beschrijven. Zie de naamruimte-uitsplitsing hieronder voor details.
• Voorbeeld: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Methode: resources/{namespace}/read — standaard naamruimte: work-times.
• Parameters: uri (verplicht) — de resource-URI, bijv. /api/work-times.
• allowPrefixes: maakt cross-naamruimte-matches mogelijk. Elke URI die begint met een toegestaan voorvoegsel wordt geaccepteerd.
• {current} oplossing: {current} in medewerker-queryparameters wordt automatisch opgelost naar /api/employees/me.
• Automatische standaarden: work-times voegt date[after]/date[before] toe (laatste 30 dagen), employees voegt itemsPerPage=200 toe, holidays/vacations voegen pagineringstandaarden toe.
• Verrijking: Responsibilities read volgt maximaal 10 @id-links om titel/naam-velden te verrijken.
• Logische naamruimte: retourneert aan serverzijde berekende samenvattingen in plaats van ruwe API-payloads.
• Reactie: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Methode: resources/{namespace}/write — alleen resources met allowWrite accepteren schrijfacties.
• Routing: POST voor aanmaken, PATCH (met application/merge-patch+json) als de URI eindigt op een ID. Overschrijven via params.contentType.
• Aanmaakpaden: /api/.../create forceert POST zelfs als er een ID aanwezig is.
• IRI-conventie: params.uri gebruikt /api/...-paden, maar entiteitsreferenties in JSON-payloads moeten upstream IRI's gebruiken (bijv. "project": "/projects/1", niet "/api/projects/1").
• Schrijfbare naamruimten: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Logische schrijfhulpen: resources/logical/write ondersteunt /logical/work-times/log (POST naar /api/work-times), /logical/recruiting/resource-requests/update?id=<id> en /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Ingebouwde agents

• EmployeeAgent (employee): Dagelijkse operaties — werktijd registreren, verlof controleren, toewijzingen bekijken. Toegang: elke geauthenticeerde gebruiker (gescopet op token/instantie).
• ManagerAgent (manager): Ondersteuning project-/engineeringmanager — tarieven, bezetting, kosten, goedkeuringen. Vereist: project_manager- of admin-rol.
• ExecutiveAgent (executive): Managementoverzichten — KPI's, budgetten, samenvattingen, goedkeuringen. Vereist: admin-, executive-, director-, vp- of c-level-rol.
• HRManagerAgent (hr): HR en verlof — verlofsaldi, verlofhistorie, teamverlof. Toegang: elke geauthenticeerde gebruiker.
• AccountancyAgent (accountancy): Financiële vragen — transacties weergeven, bedragen samenvatten. Toont nooit bijlage-URL's. Toegang: elke geauthenticeerde gebruiker.
• RecruiterAgent (recruiter): Werving — openstaande functies weergeven, kandidaten zoeken/aanmaken, koppelen aan functies, notities toevoegen. Vereist: candidates_manager-, admin- of recruiter-rol.
• OnboardingAgent (onboarding): Begeleiding nieuwe gebruikers — installatiehulp, navigatie, "waar vind ik X"-antwoorden. Toegang: elke geauthenticeerde gebruiker.
• TechAgent (tech): Technische installatie — MCP/ChatGPT-inloggegevensverzoeken. Genereert per-gebruiker clientinloggegevens na beheerdersgoedkeuring. Toegang: open voor alle rollen (zal worden aangescherpt).
• Agentselectie: Gebruik employee voor persoonlijke taken; hr voor verlof/vakantie; manager voor bezetting/kosten; executive voor KPI's; accountancy voor financiën; recruiter voor kandidaten; onboarding voor installatie.
• Toegangsmodel: Rolcontroles gebruiken Flowtly-rollen/bevoegdheden/rechten. Beperkte agents weigeren acties als er geen vereiste rol overeenkomt. Alle agents gebruiken uitsluitend de MCP API-tool — geen externe services.

Logische naamruimte — berekende samenvattingen

• Werktijdsamenvattingen: /logical/work-times/summary — geaggregeerde uren per medewerker/project. Ondersteunt date[after]/date[before] (standaard laatste 7 dagen).
• Medewerkersamenvatting: /logical/employees/summary — personeelsbestand, afdelingen en statusoverzicht.
• Projectensamenvatting: /logical/projects/summary — actieve projecten, factureringstypen en klantdistributie.
• Medewerkerwerktijden: /logical/employee-work-times/summary — bezettingsoverzicht per medewerker.
• Projecttarieven: /logical/project-rates/summary — tariefkaarten en factureringstariefoverzicht.
• Transacties: /logical/transactions/summary — uitgaventotalen, categorisering en trends.
• Projectwinstgevendheid: /logical/project-profitability/summary — omzet versus kosten per project.
• Budgetgroepen: /logical/budget-groups/summary — budgetgroeptoewijzingen en burn-status.
• Budgetten: /logical/budgets/summary — individueel budgetverbruik en waarschuwingen.
• Bedrijfsonboarding: /logical/company-onboarding/status — voortgang van werkruimteconfiguratie en openstaande stappen.
• Openstaande functies: /logical/recruiting/open-roles — niet-ingevulde resource-requests en wervingspijplijn.
• Kandidaten: /logical/recruiting/candidates — stagedistributie van kandidatenpijplijn.
• Verlof: /logical/holidays — geaggregeerde verlofgegevens en teambeschikbaarheid.
• Werktijdlog (schrijven): /logical/work-times/log — POST maakt een werktijdvermelding aan via /api/work-times.

Caching & prestaties

• Redis logische cache: Optionele cache voor logisch lezen. Kan Redis delen met de hoofd-API voor invalidatiepatronen.
• Omgevingsvariabelen: MCP_LOGICAL_CACHE_ENABLED (automatisch ingeschakeld als Redis-URL aanwezig is), MCP_LOGICAL_CACHE_REDIS_URL (fallbacks: REDIS_URL, CACHE_REDIS_URL).
• Sleutelformaat: Voorvoegsel mcp:logical:v1: — gescopet op instantie + principal, bevat genormaliseerde logische URI. Configureer voorvoegsel via MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 seconden (24 uur). Configureren via MCP_LOGICAL_CACHE_TTL_SECONDS.

Foutafhandeling

• Standaard JSON-RPC-fout: {"jsonrpc":"2.0","id":"...","error":{"code":-32000,"message":"Upstream Flowtly API failed","data":{"status":502}}}
• Veelvoorkomende foutcodes: -32700 (parseerfout), -32600 (ongeldig verzoek), -32601 (methode niet gevonden), -32000 (upstream API-fout).
• Het veld data.status weerspiegelt de HTTP-statuscode van de upstream Flowtly API als die beschikbaar is.

Aanvullende opmerkingen

• allowPrefixes: Laat resources/read URI's accepteren die beginnen met toegestane voorvoegsels, waardoor cross-naamruimte-lookups mogelijk worden.
• OpenAPI-referentie: Beschikbaar op public/mcp/openapi.json (gekopieerd naar dist/mcp/openapi.json bij bouwtijd).
• LLM-intentiecontracten: Router + manager-patronen gedocumenteerd in docs/llm-intent-architecture.md, geïmplementeerd in packages/agent/src/intents/contract.ts.
• Paginering: Standaarden worden automatisch per naamruimte toegepast. Overschrijf met expliciete queryparameters indien nodig.

Naamruimtereferentie — resources/list per naamruimte