Ship safer agents with Flowtly MCP documentation

How to stay current

1. Run the sync command after MCP updates ship.
2. Restart your agent stack to pick up capability changes.
3. Bookmark this page for the latest Flowtly MCP guidance.

What's inside

• Auth, CORS, and caching rules for MCP endpoints.
• 19 resource namespaces with list/read/write operations.
• 8 built-in agents with role-based access control.
• 14 logical summaries for computed analytics.
• JSON-RPC payloads, code examples, and integration tips.

Quickstart

• Step 1 — Get a token: Navigate to Flowtly Workspace → Agent Tokens and generate a client token.
• Step 2 — Initialize: POST to https://mcp.flowtly.eu/mcp with {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Step 3 — Read data: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Step 4 — Write 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\"}"}]}}
• All requests use Authorization: Bearer <YOUR_TOKEN> and Content-Type: application/json.

Transport & Auth

• Base URL (prod): https://mcp.flowtly.eu
• Endpoints: POST /mcp (JSON-RPC entry), GET /health (liveness check)
• Auth: Authorization: Bearer <token> (preferred). Fallback: FLOWTLY_API_KEY env var. Token generation: workspace.flowtly.eu/user/agent-tokens
• Content-Type: application/json. Body: JSON-RPC 2.0 {"jsonrpc":"2.0","id":"...","method":"...","params":{...}}
• CORS: Credentials allowed from https://workspace.flowtly.eu only. Never combine Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true.
• Upstream API: https://api.flowtly.eu — the MCP server proxies all requests to the Flowtly REST API.

initialize

• Negotiates protocol version, capabilities, and available namespaces.
• Request: {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Response capabilities: {"resources":{"list":true,"read":true,"write":true}}
• Available 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

• Method: resources/{namespace}/list — default namespace: work-times when omitted.
• Namespaces (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.
• Returns an array of {uri, name} objects describing available resources per namespace. See the namespace breakdown below for details.
• Example: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Method: resources/{namespace}/read — default namespace: work-times.
• Params: uri (required) — the resource URI, e.g. /api/work-times.
• allowPrefixes: enables cross-namespace matches. Any URI that starts with an allowed prefix is accepted.
• {current} resolution: {current} in employee query params auto-resolves to /api/employees/me.
• Auto-defaults: work-times adds date[after]/date[before] (last 30 days), employees adds itemsPerPage=200, holidays/vacations add pagination defaults.
• Enrichment: Responsibilities read follows up to 10 @id links to enrich title/name fields.
• Logical namespace: returns server-side computed summaries instead of raw API payloads.
• Response: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Method: resources/{namespace}/write — only resources with allowWrite accept writes.
• Routing: POST for creation, PATCH (with application/merge-patch+json) when URI ends with an ID. Override via params.contentType.
• Create paths: /api/.../create forces POST even if an ID is present.
• IRI convention: params.uri uses /api/... paths, but entity references inside JSON payloads must use upstream IRIs (e.g. "project": "/projects/1", not "/api/projects/1").
• Writable namespaces: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Logical write helpers: resources/logical/write supports /logical/work-times/log (POST to /api/work-times), /logical/recruiting/resource-requests/update?id=<id> and /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Built-in agents

• EmployeeAgent (employee): Day-to-day operations — log work time, check vacations, see assignments. Access: any authenticated user (scoped by token/instance).
• ManagerAgent (manager): Project/eng manager support — rates, staffing, costs, approvals. Requires: project_manager or admin role.
• ExecutiveAgent (executive): Leadership snapshots — KPIs, budgets, rollups, approvals. Requires: admin, executive, director, vp, or c-level role.
• HRManagerAgent (hr): HR and leave — vacation balances, leave history, team holidays. Access: any authenticated user.
• AccountancyAgent (accountancy): Finance queries — list transactions, summarize amounts. Never surfaces attachment URLs. Access: any authenticated user.
• RecruiterAgent (recruiter): Recruiting — list open roles, search/create candidates, attach to roles, add notes. Requires: candidates_manager, admin, or recruiter role.
• OnboardingAgent (onboarding): New user guidance — setup help, navigation, "where to find X" answers. Access: any authenticated user.
• TechAgent (tech): Technical setup — MCP/ChatGPT credential requests. Generates per-user client credentials after admin approval. Access: open to all roles (will be tightened).
• Agent selection: Use employee for personal tasks; hr for leave/vacation; manager for staffing/costs; executive for KPIs; accountancy for finance; recruiter for candidates; onboarding for setup.
• Access model: Role checks use Flowtly roles/authorities/permissions. Restricted agents refuse actions when no required role matches. All agents use the MCP API tool only — no external services.

Logical namespace — computed summaries

• Work-time summaries: /logical/work-times/summary — aggregated hours by employee/project. Supports date[after]/date[before] (defaults last 7 days).
• Employee summary: /logical/employees/summary — headcount, departments, and status overview.
• Projects summary: /logical/projects/summary — active projects, billing types, and client distribution.
• Employee work-times: /logical/employee-work-times/summary — per-employee utilization breakdown.
• Project rates: /logical/project-rates/summary — rate cards and billing rate overview.
• Transactions: /logical/transactions/summary — spend totals, categorization, and trends.
• Project profitability: /logical/project-profitability/summary — revenue vs cost per project.
• Budget groups: /logical/budget-groups/summary — budget group allocations and burn status.
• Budgets: /logical/budgets/summary — individual budget utilization and alerts.
• Company onboarding: /logical/company-onboarding/status — workspace setup progress and pending steps.
• Open roles: /logical/recruiting/open-roles — unfilled resource requests and hiring pipeline.
• Candidates: /logical/recruiting/candidates — candidate pipeline stage distribution.
• Holidays: /logical/holidays — aggregated leave data and team availability.
• Work-time log (write): /logical/work-times/log — POST creates a work-time entry via /api/work-times.

Caching & performance

• Redis logical cache: Optional cache for logical reads. Can share Redis with the main API for invalidation patterns.
• Env vars: MCP_LOGICAL_CACHE_ENABLED (auto-enabled when Redis URL exists), MCP_LOGICAL_CACHE_REDIS_URL (fallbacks: REDIS_URL, CACHE_REDIS_URL).
• Key format: Prefix mcp:logical:v1: — scoped by instance + principal, includes normalized logical URI. Configure prefix via MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 seconds (24 hours). Configure via MCP_LOGICAL_CACHE_TTL_SECONDS.

Error handling

• Standard JSON-RPC error: {"jsonrpc":"2.0","id":"...","error":{"code":-32000,"message":"Upstream Flowtly API failed","data":{"status":502}}}
• Common error codes: -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32000 (upstream API failure).
• The data.status field mirrors the HTTP status code from the upstream Flowtly API when available.

Additional notes

• allowPrefixes: Lets resources/read accept URIs that start with allowed prefixes, enabling cross-namespace lookups.
• OpenAPI reference: Available at public/mcp/openapi.json (copied to dist/mcp/openapi.json at build time).
• LLM intent contracts: Router + manager patterns documented in docs/llm-intent-architecture.md, implemented in packages/agent/src/intents/contract.ts.
• Pagination: Defaults are applied automatically per namespace. Override with explicit query params when needed.

Namespace reference — resources/list by namespace