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.

Transport & Auth

• Endpoints: POST /mcp (JSON-RPC Entry), GET /health (Liveness), POST /api/chat (Konsolen-Proxy; benötigt Authorization: Bearer <token>)
• 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": {...} }

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).

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).

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.

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=<id> und /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

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).

Fehlerform

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }

Hinweise

• allowPrefixes erlaubt resources/read URIs zu akzeptieren, die mit erlaubten Präfixen starten.
• OpenAPI-ähnliche Referenz verfügbar unter public/mcp/openapi.json.

resources/list nach Namespace