Sichere Agenten mit der Flowtly MCP-Dokumentation bauen

So bleibst du aktuell

1. Führe den Sync-Befehl nach jedem MCP-Update aus.
2. Starte deinen Agent-Stack neu, um neue Fähigkeiten zu übernehmen.
3. Setze diese Seite als Lesezeichen für die neuesten MCP-Hinweise.

Inhalte

• Auth- und API-Key-Regeln für MCP-Endpoints.
• Resource-Schemas für Knowledge Base, Blog, Release Notes, Investoren und Produkt-Updates.
• JSON-RPC-Payloads sowie Lese-/Schreibhinweise für Agenten.
• 14 logische Zusammenfassungen für berechnete Analysen.
• JSON-RPC Payloads, Codebeispiele und Integrationstipps.

Schnellstart

• Schritt 1 — Token abrufen: Navigieren Sie zu Flowtly Workspace → Agent Tokens und generieren Sie einen Client-Token.
• Schritt 2 — Initialisieren: POST an https://mcp.flowtly.eu/mcp mit {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Schritt 3 — Daten lesen: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Schritt 4 — Daten schreiben: 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 Anfragen verwenden Authorization: Bearer <YOUR_TOKEN> und Content-Type: application/json.

Transport & Auth

• Endpoints: POST /mcp (JSON-RPC Entry), GET /health (Liveness), POST /api/chat (Konsolen-Proxy; benötigt Authorization: Bearer )
• Headers: Authorization Bearer Token (bevorzugt; Fallback FLOWTLY_API_KEY), instance-Header optional und wird durchgereicht
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Anmeldeinformationen nur von https://workspace.flowtly.eu erlaubt. Kombinieren Sie niemals Access-Control-Allow-Origin: * mit Access-Control-Allow-Credentials: true.
• Upstream-API: https://api.flowtly.eu — der MCP-Server leitet alle Anfragen an die Flowtly REST API weiter.

initialize

• Handelt Fähigkeiten und Namespaces aus.
• Beispiel-Parameter: { "protocolVersion": "2024-11-05" }
• Gibt Fähigkeiten (list, read, write) und Namespaces zurück (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Verfügbare Namespaces: 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 (Standard-Namespace: work-times, falls weggelassen)
• Namespaces: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Liefert URIs pro Namespace (siehe Aufschlüsselung unten).
• Beispiel: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Methode: resources/{namespace}/read (Standard-Namespace: work-times).
• Parameter inkl. uri, z. B. /api/work-times
• allowPrefixes ermöglicht Cross-Namespace-Matches; {current} wird zu /api/employees/me aufgelöst.
• Manche Ressourcen fügen Defaults hinzu (work-times: Datumsgrenzen; employees: itemsPerPage; holidays/vacations: Pagination-Defaults).
• Responsibilities folgt bis zu 10 @id-Links, um Titel/Namen anzureichern.
• Namespace logical liefert serverseitige Summaries statt Rohdaten.
• Liefert den contents-Payload der zugrunde liegenden Flowtly-API.
• Antwort: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Nur Ressourcen mit allowWrite akzeptieren Writes; POST, außer die URI endet mit einer ID (dann PATCH mit application/merge-patch+json).
• /api/.../create erzwingt POST, auch bei vorhandener ID; Typ via params.contentType überschreibbar.
• Logical Write-Helper: resources/logical/write unterstützt /logical/recruiting/resource-requests/update?id= und /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• IRI-Konvention: params.uri verwendet /api/... Pfade, aber Entitätsreferenzen innerhalb von JSON-Payloads müssen Upstream-IRIs verwenden (z.B. "project": "/projects/1", nicht "/api/projects/1").
• Beschreibbare Namespaces: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Logische Schreibhelfer: resources/logical/write unterstützt /logical/work-times/log (POST an /api/work-times), /logical/recruiting/resource-requests/update?id=<id> und /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Eingebaute Agenten

• EmployeeAgent (employee): Tägliche Operationen — Arbeitszeiten erfassen, Urlaube prüfen, Zuweisungen einsehen. Zugriff: jeder authentifizierte Benutzer (begrenzt durch Token/Instanz).
• ManagerAgent (manager): Unterstützung für Projekt-/Ingenieurmanager — Tarife, Personalbesetzung, Kosten, Genehmigungen. Erfordert: project_manager- oder admin-Rolle.
• ExecutiveAgent (executive): Führungskennzahlen — KPIs, Budgets, Rollups, Genehmigungen. Erfordert: admin-, executive-, director-, vp- oder c-level-Rolle.
• HRManagerAgent (hr): HR und Abwesenheiten — Urlaubssalden, Abwesenheitshistorie, Teamfeiertage. Zugriff: jeder authentifizierte Benutzer.
• AccountancyAgent (accountancy): Finanzabfragen — Transaktionen auflisten, Beträge zusammenfassen. Zeigt niemals Anhang-URLs an. Zugriff: jeder authentifizierte Benutzer.
• RecruiterAgent (recruiter): Recruiting — offene Stellen auflisten, Kandidaten suchen/erstellen, Rollen zuweisen, Notizen hinzufügen. Erfordert: candidates_manager-, admin- oder recruiter-Rolle.
• OnboardingAgent (onboarding): Anleitung für neue Benutzer — Einrichtungshilfe, Navigation, Antworten auf "wo finde ich X". Zugriff: jeder authentifizierte Benutzer.
• TechAgent (tech): Technische Einrichtung — MCP/ChatGPT-Anmeldeanfragen. Generiert pro Benutzer Client-Anmeldeinformationen nach Genehmigung durch den Administrator. Zugriff: offen für alle Rollen (wird eingeschränkt).
• Agentenauswahl: Verwenden Sie employee für persönliche Aufgaben; hr für Abwesenheiten/Urlaub; manager für Personalbesetzung/Kosten; executive für KPIs; accountancy für Finanzen; recruiter für Kandidaten; onboarding für die Einrichtung.
• Zugriffsmodell: Rollenprüfungen verwenden Flowtly Rollen/Autoritäten/Berechtigungen. Eingeschränkte Agenten lehnen Aktionen ab, wenn keine erforderliche Rolle übereinstimmt. Alle Agenten verwenden ausschließlich das MCP API-Tool — keine externen Dienste.

Namespace logical (/logical/*)

• Read-only Summaries: work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Recruiting-Summaries: company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Holiday-Summaries: logical/holidays.
• Beispiel: /logical/work-times/summary unterstützt date[after]/date[before] (Standard letzte 7 Tage).
• Projektraten: /logical/project-rates/summary — Ratenkarten und Abrechnungssatz-Übersicht.
• Transaktionen: /logical/transactions/summary — Ausgaben-Gesamtsummen, Kategorisierung und Trends.
• Projektrentabilität: /logical/project-profitability/summary — Umsatz vs. Kosten pro Projekt.
• Budgetgruppen: /logical/budget-groups/summary — Budgetgruppen-Zuweisungen und Ausgabenstatus.
• Budgets: /logical/budgets/summary — individuelle Budgetauslastung und Warnmeldungen.
• Unternehmens-Onboarding: /logical/company-onboarding/status — Fortschritt der Workspace-Einrichtung und ausstehende Schritte.
• Offene Stellen: /logical/recruiting/open-roles — unbesetzte Ressourcenanfragen und Einstellungspipeline.
• Kandidaten: /logical/recruiting/candidates — Verteilung der Kandidaten in der Pipeline nach Phasen.
• Feiertage: /logical/holidays — aggregierte Urlaubsdaten und Teamverfügbarkeit.
• Arbeitszeiterfassung (schreiben): /logical/work-times/log — POST erstellt einen Arbeitszeiteintrag über /api/work-times.

Caching & Performance

• Redis logischer Cache: Optionaler Cache für logische Lesevorgänge. Kann Redis mit der Haupt-API für Invalidierungsmuster teilen.
• Umgebungsvariablen: MCP_LOGICAL_CACHE_ENABLED (automatisch aktiviert, wenn Redis-URL existiert), MCP_LOGICAL_CACHE_REDIS_URL (Rückgriffe: REDIS_URL, CACHE_REDIS_URL).
• Schlüsselformat: Präfix mcp:logical:v1: — nach Instanz + Prinzipal begrenzt, enthält eine normalisierte logische URI. Konfigurieren Sie das Präfix über MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 Sekunden (24 Stunden). Konfigurieren Sie über MCP_LOGICAL_CACHE_TTL_SECONDS.

Fehlerform

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Gängige Fehlercodes: -32700 (Analysefehler), -32600 (ungültige Anfrage), -32601 (Methode nicht gefunden), -32000 (Fehler der Upstream-API).
• Das Feld data.status spiegelt den HTTP-Statuscode der Upstream Flowtly API wider, sofern verfügbar.

Hinweise

• allowPrefixes erlaubt resources/read URIs zu akzeptieren, die mit erlaubten Präfixen starten.
• OpenAPI-ähnliche Referenz verfügbar unter public/mcp/openapi.json.
• LLM Intent-Verträge: Router- + Manager-Muster, dokumentiert in docs/llm-intent-architecture.md, implementiert in packages/agent/src/intents/contract.ts.
• Paginierung: Standardwerte werden automatisch pro Namespace angewendet. Bei Bedarf mit expliziten Abfrageparametern überschreiben.

resources/list nach Namespace