Leverera säkrare agenter med Flowtly MCP‑dokumentation

Så håller du dig aktuell

1. Kör sync‑kommandot ovan efter varje MCP‑uppdatering.
2. Starta om agentstacken för att plocka upp capability‑ändringar.
3. Bokmärk sidan för senaste Flowtly MCP‑guiden.

Innehåll

• Auth‑ och API‑nyckelregler för MCP‑endpoints.
• Resursscheman för knowledge base, blogg, releaser, investerare och produktuppdateringar.
• JSON‑RPC‑payloads och tips för skriv/läs för agenter.
• 14 logiska sammanfattningar för beräknad analys.
• JSON-RPC nyttolaster, kodexempel och integrationstips.

Snabbstart

• Steg 1 — Hämta en token: Navigera till Flowtly Workspace → Agent Tokens och generera en klienttoken.
• Steg 2 — Initiera: POST till https://mcp.flowtly.eu/mcp med {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Steg 3 — Läs data: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Steg 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\"}"}]}}
• Alla förfrågningar använder Authorization: Bearer <YOUR_TOKEN> och Content-Type: application/json.

Transport & Auth

• Endpoints: POST /mcp (JSON-RPC-ingång), GET /health (liveness), POST /api/chat (konsolproxy; kräver Authorization: Bearer )
• Headers: Authorization Bearer token (föredras; fallback FLOWTLY_API_KEY), instance-header är valfri och vidarebefordras
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Autentiseringsuppgifter tillåts endast från https://workspace.flowtly.eu. Kombinera aldrig Access-Control-Allow-Origin: * med Access-Control-Allow-Credentials: true.
• Uppströms API: https://api.flowtly.eu — MCP-servern proxyservrar alla förfrågningar till Flowtly REST API.

initialize

• Förhandlar capabilities och namespaces.
• Exempelparametrar: { "protocolVersion": "2024-11-05" }
• Returnerar capabilities (list, read, write) och namespaces (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Tillgängliga namnområden: 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

• Metod: resources/{namespace}/list (standard-namespace: work-times om utelämnad)
• Namespaces: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Returnerar URIs per namespace (se uppdelning nedan).
• Exempel: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Metod: resources/{namespace}/read (standard-namespace: work-times).
• Parametrar inkluderar uri, t.ex. /api/work-times
• allowPrefixes möjliggör cross-namespace-träffar; {current} blir /api/employees/me.
• Vissa resurser lägger till standardvärden (work-times lägger till datumgränser; employees lägger till itemsPerPage; holidays/vacations lägger till paginering).
• Responsibilities följer upp till 10 @id-länkar för att berika titel/namn.
• Namespace logical returnerar serversidesammanfattningar istället för råpayloads.
• Returnerar contents-payloaden från underliggande Flowtly-API.
• Svar: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Endast resurser med allowWrite accepterar skrivning; POST om inte URI slutar med id (då PATCH med application/merge-patch+json).
• /api/.../create tvingar POST även med id; typ kan styras via params.contentType.
• Logiskt write-hjälpmedel: resources/logical/write stöder /logical/recruiting/resource-requests/update?id= och /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• IRI-konvention: params.uri använder /api/...-sökvägar, men entitetsreferenser inuti JSON-nyttolaster måste använda uppströms IRIs (t.ex. "project": "/projects/1", inte "/api/projects/1").
• Skrivbara namnområden: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Logiska skrivhjälpmedel: resources/logical/write stöder /logical/work-times/log (POST till /api/work-times), /logical/recruiting/resource-requests/update?id=<id> och /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Inbyggda agenter

• EmployeeAgent (employee): Dagliga operationer — logga arbetstid, kontrollera semester, se tilldelningar. Åtkomst: valfri autentiserad användare (begränsas av token/instans).
• ManagerAgent (manager): Stöd för projekt-/ing-chef — priser, bemanning, kostnader, godkännanden. Kräver: project_manager- eller adminroll.
• ExecutiveAgent (executive): Ledarskapsöversikter — KPIer, budgetar, sammanställningar, godkännanden. Kräver: admin-, executive-, director-, vp- eller c-level-roll.
• HRManagerAgent (hr): HR och ledighet — semestersaldon, ledighetshistorik, teamhelgdagar. Åtkomst: valfri autentiserad användare.
• AccountancyAgent (accountancy): Finansförfrågningar — lista transaktioner, summera belopp. Visar aldrig URL:er för bilagor. Åtkomst: valfri autentiserad användare.
• RecruiterAgent (recruiter): Rekrytering — lista öppna roller, sök/skapa kandidater, koppla till roller, lägg till anteckningar. Kräver: candidates_manager-, admin- eller recruiter-roll.
• OnboardingAgent (onboarding): Vägledning för nya användare — installationshjälp, navigering, svar på "var hittar jag X". Åtkomst: valfri autentiserad användare.
• TechAgent (tech): Teknisk installation — MCP/ChatGPT-autentiseringsförfrågningar. Genererar klientuppgifter per användare efter administratörsgodkännande. Åtkomst: öppen för alla roller (kommer att stramas åt).
• Agentval: Använd employee för personliga uppgifter; hr för ledighet/semester; manager för bemanning/kostnader; executive för KPIer; accountancy för ekonomi; recruiter för kandidater; onboarding för installation.
• Åtkomstmodell: Rollkontroller använder Flowtly-roller/behörigheter. Begränsade agenter nekar åtgärder när ingen nödvändig roll matchar. Alla agenter använder endast MCP API-verktyget — inga externa tjänster.

Namespace logical (/logical/*)

• Skrivskyddade sammanfattningar: work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Recruiting-sammanfattningar: company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Holidays-sammanfattningar: logical/holidays.
• Exempel: /logical/work-times/summary stöder date[after]/date[before] (standard senaste 7 dagarna).
• Projekttaxor: /logical/project-rates/summary — prislistor och översikt över debiteringspriser.
• Transaktioner: /logical/transactions/summary — totala utgifter, kategorisering och trender.
• Projektlönsamhet: /logical/project-profitability/summary — intäkter kontra kostnader per projekt.
• Budgetgrupper: /logical/budget-groups/summary — budgetgruppstilldelningar och förbrukningsstatus.
• Budgetar: /logical/budgets/summary — individuell budgetutnyttjande och varningar.
• Företagsintroduktion: /logical/company-onboarding/status — framsteg för arbetsyteinstallation och väntande steg.
• Öppna roller: /logical/recruiting/open-roles — obesatta resursförfrågningar och rekryteringspipeline.
• Kandidater: /logical/recruiting/candidates — distribution av kandidatpipeline-steg.
• Helgdagar: /logical/holidays — aggregerad ledighetsdata och teamtillgänglighet.
• Arbetstidslogg (skriv): /logical/work-times/log — POST skapar en arbetstidspost via /api/work-times.

Cachelagring & prestanda

• Redis logisk cache: Valfri cache för logiska läsningar. Kan dela Redis med huvud-API:t för invalidationsmönster.
• Miljövariabler: MCP_LOGICAL_CACHE_ENABLED (aktiveras automatiskt när Redis URL finns), MCP_LOGICAL_CACHE_REDIS_URL (reservadresser: REDIS_URL, CACHE_REDIS_URL).
• Nyckelformat: Prefix mcp:logical:v1: — avgränsat av instans + huvudpart, inkluderar normaliserad logisk URI. Konfigurera prefix via MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 sekunder (24 timmar). Konfigurera via MCP_LOGICAL_CACHE_TTL_SECONDS.

Felformat

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Vanliga felkoder: -32700 (tolkningsfel), -32600 (ogiltig begäran), -32601 (metod hittades ej), -32000 (uppströms API-fel).
• Fältet data.status speglar HTTP-statuskoden från uppströms Flowtly API när det är tillgängligt.

Noteringar

• allowPrefixes gör att resources/read accepterar URIs som startar med tillåtna prefix.
• OpenAPI-lik referens finns i public/mcp/openapi.json.
• LLM avsiktskontrakt: Router + hanterarmönster dokumenterade i docs/llm-intent-architecture.md, implementerade i packages/agent/src/intents/contract.ts.
• Sidnumrering: Standardinställningar tillämpas automatiskt per namnrymd. Åsidosätt med explicita frågeparametrar vid behov.

resources/list per namespace