Sviluppa con l'IA

Flowie Exchange è progettato per essere guidato dall'IA. Punta Claude Desktop, Claude Code, Cursor, n8n o il tuo agente personalizzato all'API e potrà inviare, ricevere e gestire fatture elettroniche Peppol come chiamate di strumenti native — senza codice di collegamento, senza wrapper su misura. Questa pagina è l'hub di ogni superficie IA: i server MCP, la documentazione pronta per gli agenti e l'onboarding degli agenti in self-service.

Strumenti IA

Tre modi per mettere Flowie Exchange davanti a un agente. La maggior parte delle integrazioni inizia dal server MCP.

Server MCP

Flowie pubblica due server Model Context Protocol, ciascuno in produzione e in staging. Collegane uno a Claude, ChatGPT, Cursor, VS Code o Claude Code e accedi con le tue normali credenziali Flowie (SSO e Google inclusi): nessuna chiave API, niente da chiedere prima a Flowie.

Quale server mi serve?

• App (/agent-hub/mcp) — ciò che serve alla maggior parte delle persone: usare l'applicazione Flowie tramite un LLM (Claude, ChatGPT, Cursor…). Richieste di acquisto, approvazioni, attività, budget, flow, moduli, partner, pagamenti, documenti. Agisce come l'utente connesso, con esattamente i suoi permessi. Solo accesso.
• API Exchange (/exchange/mcp) — per le integrazioni: un sistema che parla con Flowie (ERP, script, backend, pipeline automatiche). Inviare, ricevere, validare e seguire fatture elettroniche, aziende, partner, directory. Di solito con una chiave API; anche l'accesso funziona.

Puoi registrarli entrambi nello stesso client. Non condividono le credenziali: una chiave API funziona solo sul server API Exchange, e il server App accetta solo un accesso. back.p2p-flowie.com è la produzione; back.flowie.ink è lo staging.

Anche il volume decide. Il server App lavora al ritmo di una persona: 60 richieste al minuto per utente, un oggetto per chiamata; oltre, il 429 indica questo server come via d'uscita. Il server API Exchange porta il volume: il budget di una chiave API va da 120 a 2.400 richieste al minuto secondo il piano (vedi Limiti di frequenza & quote), send_documents_batch invia molti documenti in una chiamata, e le instructions di ciascun server nominano l'altro: un agente collegato a quello sbagliato sa dove andare.

Creare un documento è una sola chiamata su entrambi, con lo stesso vocabolario. Sul server API Exchange, send_document con type, from, to e un document con number, issueDate, currency e lines (description, quantity, unitPrice, vatRate in percentuale) crea il documento, ne calcola i totali e lo invia; una Idempotency-Key rende sicuro un nuovo tentativo (riferimento). Sul server App, create_transaction_document con documentType, number, issuedAt, l'altra parte (buyerId quando vendi, sellerId quando compri) e lineItems (quantity, unitPrice, taxRate in percentuale) lo crea nell'app Flowie, totali calcolati, senza inviarlo da nessuna parte.

Endpoint

…/exchange/mcp/full funziona ancora: è un alias del server API Exchange, mantenuto perché le configurazioni esistenti continuino a funzionare. Usa /exchange/mcp per le nuove installazioni.

Sul server App, list_my_organizations elenca le organizzazioni a cui hai accesso, ogni strumento accetta un organization_id facoltativo, e search_flowie_api / call_flowie_api raggiungono qualsiasi altra operazione della piattaforma. Il server API Exchange espone uno strumento per ogni operazione documentata. Nessun conteggio di strumenti è indicato qui, di proposito: gli insiemi seguono l'API. Il tuo client mostra l'insieme reale, e tools/list lo restituisce.

Il trasporto è Streamable HTTP. Il vecchio trasporto SSE non è più montato.

Avvio rapido — Claude Code

Produzione, server App:

claude mcp add --transport http flowie-app https://back.p2p-flowie.com/agent-hub/mcp

Poi esegui /mcp in Claude Code, scegli flowie-app e seleziona Authenticate. Si apre un browser sulla pagina di accesso Flowie. Per aggiungere anche il server API Exchange:

claude mcp add --transport http flowie-api https://back.p2p-flowie.com/exchange/mcp

Per progetto, versiona invece un file .mcp.json:

{
  "mcpServers": {
    "flowie-app": {
      "type": "http",
      "url": "https://back.p2p-flowie.com/agent-hub/mcp"
    }
  }
}

Avvio rapido — Claude.ai e Claude Desktop

Impostazioni → Connettori → Aggiungi connettore personalizzato, incolla l'URL, poi Connetti e accedi. Nessun client ID, nessun segreto.

https://back.p2p-flowie.com/agent-hub/mcp

ChatGPT funziona allo stesso modo: aggiungi un connettore personalizzato (modalità sviluppatore) con questo URL e autenticazione OAuth.

Avvio rapido — Cursor / VS Code

Cursor — ~/.cursor/mcp.json o .cursor/mcp.json, poi fai clic su Connect accanto al server:

{
  "mcpServers": {
    "flowie-app": {
      "url": "https://back.p2p-flowie.com/agent-hub/mcp"
    }
  }
}

VS Code — .vscode/mcp.json. VS Code usa "servers" e "type": "http":

{
  "servers": {
    "flowie-app": {
      "type": "http",
      "url": "https://back.p2p-flowie.com/agent-hub/mcp"
    }
  }
}

Avvio rapido — Amazon Quick

Amazon Quick (abbonamento Enterprise) si collega ai server MCP remoti e trasforma ogni strumento in un'azione. Un amministratore aggiunge Flowie una volta e lo condivide con il team:

1. Nella console di Amazon Quick, apri Connectors → Create for your team → Model Context Protocol (MCP).
2. Name: Flowie. MCP server endpoint: https://back.p2p-flowie.com/agent-hub/mcp. Connection type e Auth server connection type: Public network.
3. Scegli User authentication (OAuth). Flowie supporta la registrazione dinamica dei client: Amazon Quick si registra da solo, lascia vuoti ID e secret del client.
4. Create and continue, accedi dalla pagina Flowie, controlla le azioni, poi condividi il connettore.

Ogni persona accede con il proprio account Flowie, quindi le azioni girano con i suoi permessi. Aggiungi https://back.p2p-flowie.com/exchange/mcp allo stesso modo per l'API Exchange. Amazon Quick tiene i primi 100 strumenti di un server: entrambi i server elencano prima gli strumenti essenziali (inviare e cercare fatture, approvazioni, richieste e ordini d'acquisto, fornitori, budget, e search_flowie_api / call_flowie_api per tutto il resto). Quando Flowie aggiunge strumenti, scegli Sync sul connettore per caricarli.

Staging / sandbox

Stessi comandi sull'host di staging, con un account di staging:

claude mcp add --transport http flowie-app-staging https://back.flowie.ink/agent-hub/mcp
claude mcp add --transport http flowie-api-staging https://back.flowie.ink/exchange/mcp

Autenticazione

Due modi per entrare. Scegli in base a chi agisce, non al client che usi.

L'accesso segue il flusso di autorizzazione MCP standard. Una chiamata non autenticata restituisce 401 con WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"; quei metadati elencano authorization_servers: ["https://<host>/exchange"], i cui metadati (<host>/exchange/.well-known/oauth-authorization-server) indicano l'endpoint di autorizzazione <host>/exchange/oauth/authorize, l'endpoint del token <host>/exchange/v1/oauth/token e l'endpoint di registrazione <host>/exchange/v1/oauth/register. La registrazione dinamica del client è supportata (RFC 7591, client pubblico, PKCE S256), e un redirect verso la tua macchina è accettato su qualsiasi porta. La pagina di accesso è il normale login Flowie, quindi SSO e Google funzionano. Il token di accesso dura 24 ore e il client lo rinnova con un refresh token, senza un nuovo consenso.

Il token è legato al tuo account Flowie: raggiunge le organizzazioni a cui hai accesso, con i permessi che vi detieni. Un agente non può fare nulla che tu non potresti fare.

claude mcp add --transport http flowie-api https://back.p2p-flowie.com/exchange/mcp \
  --header "Authorization: Bearer flw_live_..."

Questa è la via con chiave API (chiave di produzione sull'host di produzione; una chiave flw_test_… sull'host di staging raggiunge tutti i destinatari di test della guida al sandbox — ottienine una con un clic). Dettagli completi: auth.md.

Avvio rapido — Python (SDK mcp)

Per gli agenti personalizzati, l'SDK Python ufficiale mcp parla streamable-HTTP direttamente:

# pip install mcp
import asyncio, os
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

URL = "https://back.flowie.ink/exchange/mcp"
KEY = os.environ["FLOWIE_KEY"]

async def main():
    async with streamablehttp_client(
        URL, headers={"Authorization": f"Bearer {KEY}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"{len(tools.tools)} tools available")

            # Chiamare uno strumento per nome con argomenti in stile REST
            result = await session.call_tool(
                "list_documents",
                arguments={"direction": "incoming", "status": "unread", "limit": 5},
            )
            print(result.content[0].text)

asyncio.run(main())

Catalogo degli strumenti (server API Exchange)

Il server API Exchange espone uno strumento MCP per ogni operazione documentata. I più utili per gli agenti:

Lancia tools/list via MCP per enumerare l'insieme completo con gli schemi di input e le descrizioni. Lo schema di input di ogni strumento riflette il corpo della richiesta dell'endpoint REST — vedi il riferimento API per la forma canonica.

Workflow comune — « Quali fatture sono arrivate questa settimana? »

L'agente sceglie gli strumenti giusti dal prompt; tu non fai nulla.

User: "What invoices arrived this week and which ones are still unpaid?"

Agent → list_documents({direction: "incoming", since: "2026-04-26"})
     → for each: get_document_structured({documentId})
     → for each unpaid: get_compliance_report({documentId})
     → summarises totals by supplier, flags the ones past dueDate

Workflow comune — « Invia una fattura ad ACME »

Tre strumenti, una sola catena. L'agente verifica il destinatario prima di inviare.

User: "Bill ACME BVBA €4,500 + VAT for April consulting, due in 30 days."

Agent → search_directory({q: "ACME BVBA"})            # trova il peppolId
     → verify_recipient({peppolId, documentType: "INVOICE"})
     → send_document({
         type: "invoice",
         from: "comp_abc123",
         to:   "0208:0123456789",
         document: {
           number:    "INV-2026-0451",
           issueDate: "2026-04-30",
           dueDate:   "2026-05-30",
           currency:  "EUR",
           lines: [{
             description: "Consulting — April 2026",
             quantity: 1, unit: "lot",
             unitPrice: 4500.00, vatRate: 21
           }]
         }
       })

L'agente vede il documentId + il deliveryStatus restituiti e te ne dà conto. Passa una Idempotency-Key a livello REST se vuoi sicurezza in caso di retry — MCP la trasmette come argomento dello strumento.

Workflow comune — « Segna INV-0417 come pagata »

User: "INV-2026-0417 was paid yesterday — close the loop."

Agent → search_documents({number: "INV-2026-0417"})    # → documentId
     → update_lifecycle({
         documentId,
         status: "paid",
         note: "Paid 2026-04-29 via SEPA"
       })

Il cambio di ciclo di vita attiva automaticamente la dichiarazione al PPF (FR) o allo SDI (IT) quando applicabile — l'agente non ha bisogno di saperlo. Monitora compliance.reported sul tuo flusso di webhook per la conferma. Le fatture belghe saltano questo passaggio (HERMES dismesso il 31/12/2025).

Workflow comune — « Fai l'onboarding di un nuovo fornitore »

User: "Add Globex SRL (VAT IT09876543210) as a partner and check they're on Peppol."

Agent → resolve_company({vatNumber: "IT09876543210"})   # profilo arricchito
     → verify_recipient({peppolId})                     # canReceive: true?
     → save_partner({...})                              # nel tuo CRM/ERP

HTTP diretto (senza SDK)

MCP è solo JSON-RPC su un POST HTTP. Se non vuoi l'SDK:

# 1. Inizializzare la sessione
curl -X POST https://back.flowie.ink/exchange/mcp \
  -H "Authorization: Bearer $FLOWIE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "curl", "version": "1.0"}
    }
  }'

# 2. Elencare gli strumenti
curl -X POST https://back.flowie.ink/exchange/mcp \
  -H "Authorization: Bearer $FLOWIE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Chiamare uno strumento
curl -X POST https://back.flowie.ink/exchange/mcp \
  -H "Authorization: Bearer $FLOWIE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"list_documents",
      "arguments":{"direction":"incoming","limit":5}
    }
  }'

Errori

Gli errori MCP riflettono gli errori REST sottostanti — stessi codici, stessa forma, incapsulati in JSON-RPC. Un 401 lato REST emerge come errore MCP -32001 con il codice di errore Flowie originale in data.errorCode. Vedi il catalogo degli errori per tutto ciò che potresti incontrare.

I due errori specifici di MCP:

• tool not found — questo nome di strumento non esiste su questo server. Esegui tools/list per i nomi esatti. Gli strumenti App (workflow, attività, richieste di acquisto, budget…) sono su /agent-hub/mcp, non su /exchange/mcp.
• invalid arguments — schema di input non rispettato. Lancia tools/list e segui l'inputSchema alla lettera.

Limiti di frequenza & quote

Le chiamate MCP ereditano la tua quota REST — non c'è un budget separato. Un tools/call MCP = una richiesta REST. Usa la stessa logica di backoff sull'intestazione X-Flowie-RateLimit-Remaining; l'intestazione è esposta sulla busta di risposta JSON-RPC sotto _meta.

Server App: 60 richieste JSON-RPC al minuto per utente su /agent-hub/mcp, al ritmo di una persona. Oltre, la risposta è 429 con Retry-After. Per i volumi, usa il server Exchange, che consente da 120 a 2.400 richieste al minuto a seconda del piano.

Sandbox

Punta l'agente a https://back.flowie.ink/exchange/mcp con una chiave flw_test_… e ogni funzione del sandbox funziona: errori forzati via X-Sandbox-Force-Error, destinatari simulati (0208:SIM_HAPPY, SIM_DISPUTE, TEST_AP_FAIL), simulatori di ciclo di vita, tutto. Vedi la guida al sandbox per il menu completo.

Risoluzione dei problemi

• 401 — "Unauthorized: sign in to Flowie to use these tools." Il client non ha completato l'accesso. In Claude Code esegui /mcp, scegli il server, Authenticate; altrove fai clic su Connect accanto al server.
• "Server not found" da claude.ai/api/…/mcp/start-auth/mcpsrv_… — il connettore claude.ai è stato rimosso o riaggiunto mentre Claude Code era in esecuzione. Riavvia Claude Code, oppure aggiungi il server direttamente con claude mcp add --transport http flowie-app https://back.p2p-flowie.com/agent-hub/mcp.
• Una chiave API viene rifiutata su /agent-hub/mcp — previsto: il server App accetta solo l'accesso. Usa /exchange/mcp per le chiavi.
• Chiave rifiutata sull'altro host — le chiavi flw_live_… funzionano su back.p2p-flowie.com, le chiavi flw_test_… su back.flowie.ink.

Documentazione per agenti

Tutto il sito di documentazione è pubblicato in forma leggibile dalle macchine, secondo la convenzione llms.txt. Punta un agente (o una pipeline RAG) a questi file invece di fare scraping dell'HTML — ogni pagina porta un <link rel="alternate" type="text/markdown"> perché gli strumenti li scoprano automaticamente.

Tutto ciò che sta sotto docs.get-flowie.com è raggiungibile così: https://docs.get-flowie.com/llms.txt, https://docs.get-flowie.com/llms-full.txt, e un file Markdown per endpoint sotto https://docs.get-flowie.com/llms/reference/.

Onboarding degli agenti

Un agente non ha bisogno che un umano gli consegni una chiave. Due percorsi in self-service gli permettono di provvedere da sé — vedi la guida completa all'onboarding degli agenti per entrambi.

• Bootstrap sandbox — un unico POST non autenticato restituisce una chiave flw_test_… valida 7 giorni più un'azienda sandbox di partenza. Nessun umano nel processo; ideale per prototipazione, demo e CI di agenti. Vedi il flusso di bootstrap.
• Consenso OAuth (PKCE) — quando l'agente deve agire per conto di un utente reale, il flusso di consenso in stile OAuth emette una chiave con ambito limitato, di livello produzione, dopo l'approvazione dell'utente. Vedi il flusso di consenso OAuth.