KI-Tools mit schreibgeschütztem MCP an Flowtly anbinden

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-, CORS- und Transport-Regeln für den MCP-Endpoint.
• Schreibgeschützte Ressourcen-Namespaces mit List- und Read-Operationen.
• OAuth 2.0 mit Dynamic Client Registration für die Verbindung in einem Schritt.
• 16 schreibgeschützte Tools über 10 Ressourcen-Namespaces.
• JSON-RPC Payloads, Codebeispiele und Integrationstipps.

Schnellstart

• Schritt 1 — Verbinden (OAuth): Fügen Sie https://mcp.flowtly.eu als Connector in Ihrem KI-Tool hinzu und autorisieren Sie schreibgeschützten Zugriff. In Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Vollständige Anleitung: KI-Tools verbinden.
• Schritt 2 — Initialisieren: POST an https://mcp.flowtly.eu/mcp mit {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — der Server antwortet mit Fähigkeiten {"tools":{}}.
• Schritt 3 — Tools auflisten: POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}, um die verfügbaren schreibgeschützten Tools zu entdecken (z. B. invoices.list, transactions.list, counterparties.list).
• Schritt 4 — Ein Tool aufrufen: POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. Das Ergebnis kommt als result.content[].text (ein JSON-String) an.
• 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" }
• Antwort-Fähigkeiten: {"tools":{}}
• Tools entdecken: Rufen Sie tools/list auf, um die verfügbaren schreibgeschützten Tools und ihre JSON-Schema-Eingabe zu erhalten.

tools/list

• Methode: tools/list — gibt jedes schreibgeschützte Tool zurück, das für Ihre Verbindung verfügbar ist.
• 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.
• Jeder Eintrag hat einen name, eine description und ein JSON-Schema inputSchema, das seine Argumente beschreibt.
• Beispiel: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Methode: tools/call — ein Tool anhand seines Namens mit seinen Argumenten aufrufen.
• Parameter: {"name":"<tool>","arguments":{...}}, z. B. {"name":"invoices.list","arguments":{}}.
• Argumente: folgen dem inputSchema des Tools aus tools/list (Filter, Pagination, IDs). Weglassen für sinnvolle Defaults.
• Schreibgeschützt: jedes Tool liest nur Daten — es gibt keine Schreib-Tools.
• Erst entdecken: Rufen Sie tools/list auf, um vor dem Aufruf die genauen Tool-Namen und Argument-Schemas zu sehen.
• Pagination & Filter: innerhalb von arguments gemäß dem Schema jedes Tools übergeben (z. B. Datumsbereiche, Seitengröße).
• Einzelne Datensätze: die *.get-Tools nehmen ein id-Argument und geben eine Entität zurück; die *.list-Tools geben Sammlungen zurück.
• Antwort: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — parsen Sie content[].text als JSON.

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.

Tools nach Namespace