Anslut AI‑verktyg till Flowtly med skrivskyddat MCP

Så håller du dig aktuell

1. Kör sync‑kommandot ovan efter varje MCP‑uppdatering.
2. Starta om agentstacken för att plocka upp capability‑ändringar.
3. Bokmärk sidan för senaste Flowtly MCP‑guiden.

Innehåll

• Auth-, CORS- och transportregler för MCP-endpointen.
• Skrivskyddade resursnamnrymder med list- och läsoperationer.
• OAuth 2.0 med Dynamic Client Registration för anslutning i ett steg.
• 16 skrivskyddade verktyg över 10 resursnamnrymder.
• JSON-RPC nyttolaster, kodexempel och integrationstips.

Snabbstart

• Steg 1 — Anslut (OAuth): Lägg till https://mcp.flowtly.eu som en connector i ditt AI-verktyg och godkänn skrivskyddad åtkomst. I Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Fullständig genomgång: Anslut AI-verktyg.
• Steg 2 — Initiera: POST till https://mcp.flowtly.eu/mcp med {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — servern svarar med funktioner {"tools":{}}.
• Steg 3 — Lista verktyg: POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}} för att upptäcka de tillgängliga skrivskyddade verktygen (t.ex. invoices.list, transactions.list, counterparties.list).
• Steg 4 — Anropa ett verktyg: POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. Resultatet kommer som result.content[].text (en JSON-sträng).
• Alla förfrågningar använder Authorization: Bearer <YOUR_TOKEN> och Content-Type: application/json.

Transport & auth

• Endpoints: POST /mcp (JSON-RPC-ingång), GET /health (liveness), POST /api/chat (konsolproxy; kräver Authorization: Bearer )
• Headers: Authorization Bearer token (föredras; fallback FLOWTLY_API_KEY), instance-header är valfri och vidarebefordras
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Autentiseringsuppgifter tillåts endast från https://workspace.flowtly.eu. Kombinera aldrig Access-Control-Allow-Origin: * med Access-Control-Allow-Credentials: true.
• Uppströms API: https://api.flowtly.eu — MCP-servern proxyservrar alla förfrågningar till Flowtly REST API.

initialize

• Förhandlar capabilities och namespaces.
• Exempelparametrar: { "protocolVersion": "2024-11-05" }
• Svarsfunktioner: {"tools":{}}
• Upptäck verktyg: anropa tools/list för att hämta de tillgängliga skrivskyddade verktygen och deras JSON-Schema-indata.

tools/list

• Metod: tools/list — returnerar varje skrivskyddat verktyg som är tillgängligt för din anslutning.
• Verktyg (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.
• Varje post har ett name, en description och ett JSON-Schema inputSchema som beskriver dess argument.
• Exempel: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Metod: tools/call — anropa ett verktyg med dess namn och argument.
• Params: {"name":"<tool>","arguments":{...}}, t.ex. {"name":"invoices.list","arguments":{}}.
• Argument: följ verktygets inputSchema från tools/list (filter, paginering, id:n). Utelämna för rimliga standardvärden.
• Skrivskyddad: varje verktyg läser endast data — det finns inga skrivverktyg.
• Upptäckt först: anropa tools/list för att se exakta verktygsnamn och argumentscheman innan du anropar.
• Paginering & filter: skickas inuti arguments enligt varje verktygs schema (t.ex. datumintervall, sidstorlek).
• Enskilda poster: verktygen *.get tar ett id-argument och returnerar en enda entitet; verktygen *.list returnerar samlingar.
• Svar: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — tolka content[].text som JSON.

Felformat

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Vanliga felkoder: -32700 (tolkningsfel), -32600 (ogiltig begäran), -32601 (metod hittades ej), -32000 (uppströms API-fel).
• Fältet data.status speglar HTTP-statuskoden från uppströms Flowtly API när det är tillgängligt.

Noteringar

• allowPrefixes gör att resources/read accepterar URIs som startar med tillåtna prefix.
• OpenAPI-lik referens finns i public/mcp/openapi.json.
• LLM avsiktskontrakt: Router + hanterarmönster dokumenterade i docs/llm-intent-architecture.md, implementerade i packages/agent/src/intents/contract.ts.
• Sidnumrering: Standardinställningar tillämpas automatiskt per namnrymd. Åsidosätt med explicita frågeparametrar vid behov.

Verktyg per namnrymd