Connect AI tools to Flowtly with read-only MCP

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 transport rules for the MCP endpoint.
• Read-only resource namespaces with list and read operations.
• OAuth 2.0 with Dynamic Client Registration for one-step connect.
• 16 read-only tools across 10 resource namespaces.
• JSON-RPC payloads, code examples, and integration tips.

Quickstart

• Step 1 — Connect (OAuth): Add https://mcp.flowtly.eu as a connector in your AI tool and authorize read-only access. In Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Full walkthrough: Connecting AI Tools.
• Step 2 — Initialize: POST to https://mcp.flowtly.eu/mcp with {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — the server replies with capabilities {"tools":{}}.
• Step 3 — List tools: POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}} to discover the available read-only tools (e.g. invoices.list, transactions.list, counterparties.list).
• Step 4 — Call a tool: POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. The result arrives as result.content[].text (a JSON string).
• 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: OAuth 2.0 with Dynamic Client Registration (RFC 7591). The connector signs you in and issues a short-lived Authorization: Bearer <token> scoped to one organization (read-only). Discovery: GET /.well-known/oauth-authorization-server. Walkthrough: Connecting AI Tools.
• 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: {"tools":{}}
• Discover tools: call tools/list to get the available read-only tools and their JSON-Schema input.

tools/list

• Method: tools/list — returns every read-only tool available to your connection.
• Tools (16): invoices.list/get, transactions.list, bankAccounts.list/get, counterparties.list/get, suppliers.list, contracts.list/get/paymentScheduleLines, attachments.list/get, costGroups.list, taxGroups.list, projects.list.
• Each entry has a name, a description, and a JSON-Schema inputSchema describing its arguments.
• Example: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Method: tools/call — invoke a tool by name with its arguments.
• Params: {"name":"<tool>","arguments":{...}}, e.g. {"name":"invoices.list","arguments":{}}.
• Arguments: follow the tool's inputSchema from tools/list (filters, pagination, ids). Omit for sensible defaults.
• Read-only: every tool reads data only — there are no write tools.
• Discovery first: call tools/list to see exact tool names and argument schemas before calling.
• Pagination & filters: passed inside arguments per each tool's schema (e.g. date ranges, page size).
• Single records: the *.get tools take an id argument and return one entity; the *.list tools return collections.
• Response: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — parse content[].text as JSON.

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.

Tools by namespace