Byg sikrere agenter med Flowtly MCP dokumentation

Sådan holder du dig opdateret

1. Kør synkroniseringskommandoen, når MCP-opdateringer er sendt.
2. Genstart din agent-stak for at hente kapabilitetsændringer.
3. Sæt bogmærke ved denne side for den nyeste Flowtly MCP-vejledning.

Hvad er inkluderet

• Auth, CORS og caching-regler for MCP-endpoints.
• 19 ressourcenavnerum med liste-/læse-/skrive-operationer.
• 8 indbyggede agenter med rollebaseret adgangskontrol.
• 14 logiske oversigter til beregnede analyser.
• JSON-RPC-payloads, kodeeksempler og integrationstips.

Hurtigstart

• Trin 1 — Hent en token: Naviger til Flowtly Workspace → Agent Tokens og generer en klienttoken.
• Trin 2 — Initialisér: POST til https://mcp.flowtly.eu/mcp med {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Trin 3 — Læs data: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Trin 4 — Skriv data: 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 anmodninger bruger Authorization: Bearer <YOUR_TOKEN> og Content-Type: application/json.

Transport og auth

• Base URL (prod): https://mcp.flowtly.eu
• Endpoints: POST /mcp (JSON-RPC entry), GET /health (liveness check)
• Auth: Authorization: Bearer <token> (foretrukket). Fallback: miljøvariablen FLOWTLY_API_KEY. Tokengenerering: workspace.flowtly.eu/user/agent-tokens
• Content-Type: application/json. Body: JSON-RPC 2.0 {"jsonrpc":"2.0","id":"...","method":"...","params":{...}}
• CORS: Legitimationsoplysninger tilladt kun fra https://workspace.flowtly.eu. Kombiner aldrig Access-Control-Allow-Origin: * med Access-Control-Allow-Credentials: true.
• Upstream API: https://api.flowtly.eu — MCP-serveren proxyer alle anmodninger til Flowtly REST API.

initialize

• Forhandler protokolversion, kapabiliteter og tilgængelige navnerum.
• Anmodning: {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Svarkapabiliteter: {"resources":{"list":true,"read":true,"write":true}}
• Tilgængelige navnerum: 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

• Metode: resources/{namespace}/list — standardnavnerum: work-times når udeladt.
• Navnerum (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.
• Returnerer et array af {uri, name}-objekter, der beskriver tilgængelige ressourcer per navnerum. Se navnerumsoversigten nedenfor for detaljer.
• Eksempel: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Metode: resources/{namespace}/read — standardnavnerum: work-times.
• Parametre: uri (påkrævet) — ressource-URI'en, f.eks. /api/work-times.
• allowPrefixes: aktiverer matches på tværs af navnerum. Enhver URI, der starter med et tilladt præfiks, accepteres.
• {current}-løsning: {current} i medarbejderforespørgselsparametre løses automatisk til /api/employees/me.
• Automatiske standarder: work-times tilføjer date[after]/date[before] (de seneste 30 dage), employees tilføjer itemsPerPage=200, holidays/vacations tilføjer pagineringsstandarder.
• Berigelse: Responsibilities read følger op til 10 @id-links for at berige title/name-felter.
• Logisk navnerum: returnerer serverberegnede oversigter i stedet for rå API-payloads.
• Svar: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Metode: resources/{namespace}/write — kun ressourcer med allowWrite accepterer skrivninger.
• Routing: POST til oprettelse, PATCH (med application/merge-patch+json) når URI'en slutter med et ID. Tilsidesæt via params.contentType.
• Oprettelsesstier: /api/.../create tvinger POST selv hvis et ID er til stede.
• IRI-konvention: params.uri bruger /api/...-stier, men enhedsreferencer inde i JSON-payloads skal bruge upstream-IRI'er (f.eks. "project": "/projects/1", ikke "/api/projects/1").
• Skrivbare navnerum: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Logiske skrivehjælpere: resources/logical/write understøtter /logical/work-times/log (POST til /api/work-times), /logical/recruiting/resource-requests/update?id=<id> og /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Indbyggede agenter

• EmployeeAgent (employee): Daglige opgaver — log arbejdstid, tjek fravær, se opgaver. Adgang: enhver godkendt bruger (afgrænset af token/instans).
• ManagerAgent (manager): Projekt-/teknisk lederstøtte — takster, bemanding, omkostninger, godkendelser. Kræver: rollen project_manager eller admin.
• ExecutiveAgent (executive): Ledelsesoversigter — KPI'er, budgetter, sammendrag, godkendelser. Kræver: rollen admin, executive, director, vp eller c-level.
• HRManagerAgent (hr): HR og fravær — feriesaldi, fraværshistorik, teamferier. Adgang: enhver godkendt bruger.
• AccountancyAgent (accountancy): Finansforespørgsler — vis transaktioner, opsummer beløb. Viser aldrig vedhæftnings-URL'er. Adgang: enhver godkendt bruger.
• RecruiterAgent (recruiter): Rekruttering — vis ledige stillinger, søg/opret kandidater, tilknyt til stillinger, tilføj noter. Kræver: rollen candidates_manager, admin eller recruiter.
• OnboardingAgent (onboarding): Vejledning til nye brugere — opsætningshjælp, navigation, svar på "hvor finder jeg X". Adgang: enhver godkendt bruger.
• TechAgent (tech): Teknisk opsætning — MCP/ChatGPT-legitimationsanmodninger. Genererer brugerspesifikke klientlegitimationsoplysninger efter admin-godkendelse. Adgang: åben for alle roller (vil blive strammet).
• Agentvalg: Brug employee til personlige opgaver; hr til fravær/ferie; manager til bemanding/omkostninger; executive til KPI'er; accountancy til økonomi; recruiter til kandidater; onboarding til opsætning.
• Adgangsmodel: Rollekontroller bruger Flowtly-roller/autoriteter/tilladelser. Begrænsede agenter afviser handlinger, når ingen påkrævet rolle matcher. Alle agenter bruger kun MCP API-redskabet — ingen eksterne tjenester.

Logisk navnerum — beregnede oversigter

• Tidsregistreringsoversigter: /logical/work-times/summary — aggregerede timer per medarbejder/projekt. Understøtter date[after]/date[before] (standard de seneste 7 dage).
• Medarbejderoversigt: /logical/employees/summary — medarbejderantal, afdelinger og statusoversigt.
• Projektoversigt: /logical/projects/summary — aktive projekter, faktureringstyper og kundedistribution.
• Medarbejder-tidsregistreringer: /logical/employee-work-times/summary — per-medarbejder udnyttelsesfordeling.
• Projekttakster: /logical/project-rates/summary — takstkort og faktureringstaksoversigt.
• Transaktioner: /logical/transactions/summary — forbrugstotaler, kategorisering og tendenser.
• Projektrentabilitet: /logical/project-profitability/summary — omsætning vs. omkostning per projekt.
• Budgetgrupper: /logical/budget-groups/summary — budgetgruppefordeling og forbrugsstatus.
• Budgetter: /logical/budgets/summary — individuel budgetudnyttelse og advarsler.
• Virksomhedsonboarding: /logical/company-onboarding/status — fremgang i arbejdsområdeopsætning og afventende trin.
• Åbne stillinger: /logical/recruiting/open-roles — ubesatte ressourceanmodninger og rekrutteringspipeline.
• Kandidater: /logical/recruiting/candidates — kandidatpipelinestadiefordeling.
• Ferier: /logical/holidays — aggregerede fraværsdata og teamtilgængelighed.
• Tidsregistreringslog (skriv): /logical/work-times/log — POST opretter en tidsregistrering via /api/work-times.

Caching og performance

• Redis logisk cache: Valgfri cache til logiske læsninger. Kan dele Redis med hoved-API'et til invalideringsmønstre.
• Miljøvariabler: MCP_LOGICAL_CACHE_ENABLED (aktiveres automatisk, når Redis URL eksisterer), MCP_LOGICAL_CACHE_REDIS_URL (fallbacks: REDIS_URL, CACHE_REDIS_URL).
• Nøgleformat: Præfiks mcp:logical:v1: — afgrænset af instans + principal, inkluderer normaliseret logisk URI. Konfigurér præfiks via MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 sekunder (24 timer). Konfigureres via MCP_LOGICAL_CACHE_TTL_SECONDS.

Fejlhåndtering

• Standard JSON-RPC-fejl: {"jsonrpc":"2.0","id":"...","error":{"code":-32000,"message":"Upstream Flowtly API failed","data":{"status":502}}}
• Almindelige fejlkoder: -32700 (parse-fejl), -32600 (ugyldig anmodning), -32601 (metode ikke fundet), -32000 (upstream API-fejl).
• Feltet data.status afspejler HTTP-statuskoden fra den upstream Flowtly API, når den er tilgængelig.

Yderligere noter

• allowPrefixes: Giver resources/read mulighed for at acceptere URI'er, der starter med tilladte præfikser, og muliggør opslag på tværs af navnerum.
• OpenAPI-reference: Tilgængelig på public/mcp/openapi.json (kopieres til dist/mcp/openapi.json ved byggetidspunkt).
• LLM intent-kontrakter: Router- og managermønstre dokumenteret i docs/llm-intent-architecture.md, implementeret i packages/agent/src/intents/contract.ts.
• Paginering: Standarder anvendes automatisk per navnerum. Tilsidesæt med eksplicitte forespørgselsparametre ved behov.

Navnerumreference — resources/list pr. navnerum