Plugin per agenti

Beta pubblica. Tutto ciò che questa pagina descrive funziona oggi ed è gratuito. I nomi degli strumenti, il contenuto delle skill e la superficie della CLI possono ancora cambiare tra una release e l’altra — li versioniamo e annunciamo ogni modifica nel changelog, ma non vincolate ancora un flusso di produzione a un nome di strumento preciso. Vedi Cosa significa beta.

Date al vostro agente di codice gli strumenti di Flowie Exchange, il know-how per usarli correttamente e un account che può aprire da solo. Tre superfici, una sola configurazione:

Gli strumenti e le skill sono pensati per essere installati insieme. Un server MCP da solo costringe il vostro agente a riscoprire ogni trappola della fatturazione elettronica transfrontaliera; le skill sono il punto in cui le abbiamo scritte.

Avvio rapido

Scegliete il vostro agente. Tutti i comandi qui sotto puntano alla sandbox — nessuna chiave, nessuna registrazione, e nulla di ciò che eseguite può raggiungere un’amministrazione fiscale.

Claude Code

claude mcp add flowie-exchange https://back.flowie.ink/exchange/mcp

Cursor, VS Code, Codex e qualsiasi client che parli MCP

Aggiungete il server alla configurazione MCP del vostro client:

{
  "mcpServers": {
    "flowie-exchange": {
      "url": "https://back.flowie.ink/exchange/mcp"
    }
  }
}

Ottenere una chiave senza lasciare l’agente

Il vostro agente può aprire il proprio account sandbox — senza umani, senza moduli:

curl -X POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap \
  -H 'Content-Type: application/json' -d '{}'

Restituisce una chiave flw_test_…, un’organizzazione e un’azienda. Inviatela come Authorization: Bearer <key> su ogni chiamata successiva. Per la produzione, o per agire sull’account reale di un utente, leggete Onboarding dell’agente.

Server MCP

Due endpoint, la stessa autenticazione:

L’autenticazione è un token bearer su ogni chiamata — un JWT utente o una chiave API flw_* — e l’organizzazione del token delimita ogni lettura e scrittura. Nessun movimento di denaro: i campi di pagamento sono soltanto metadati della fattura.

Il server si descrive su /.well-known/mcp/server-card.json e nomina il proprio server di autorizzazione su /.well-known/oauth-authorization-server. Un agente che segue la catena di discovery li trova entrambi senza che glieli si indichi. Catalogo completo degli strumenti e flussi di lavoro concreti: riferimento del server MCP.

Skill per agenti

Una skill è un file Markdown che insegna a un agente come svolgere un compito preciso con questa API — quale endpoint risponde, cosa significano i campi, e l’errore che sembra un successo. Non eseguono nulla, quindi non costano nulla a runtime, e sono ciò che impedisce a un agente di inventare un campo che l’API non ha.

Il catalogo è individuabile e indirizzato per contenuto:

curl https://docs.get-flowie.com/.well-known/agent-skills/index.json

Ogni voce porta una url e un digest sha256, così un client può mettere in cache una skill e accorgersi di quando cambia. Quattordici sono pubblicate oggi:

La maggior parte dei client MCP carica le skill dall’indice non appena il server è connesso. Se il vostro non lo fa, puntatelo al file grezzo — per esempio https://docs.get-flowie.com/skills/send-invoice/SKILL.md.

CLI

Beta privata. La CLI non è ancora pubblicata. Scriveteci a [email protected] e vi aggiungiamo.

La CLI copre lo stesso terreno da un terminale, per i casi in cui un modello nel processo è un rischio più che un aiuto — un job di CI, una procedura operativa, una migrazione che dovete poter rieseguire e confrontare. Avvia anche un server MCP in locale su stdio, se preferite che il vostro agente parli con un processo che avete avviato voi invece che con un endpoint che ospitiamo noi.

Documenteremo qui installazione e comandi quando uscirà dalla beta privata. Fino ad allora il server MCP ospitato qui sopra è il percorso supportato, e tutto ciò che un agente può farci resta raggiungibile in semplice HTTP: vedi il riferimento API.

Verificare che funzioni

Una sola richiesta prova l’intera catena — trasporto, discovery ed elenco degli strumenti:

curl -X POST https://back.flowie.ink/exchange/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2024-11-05","capabilities":{},
        "clientInfo":{"name":"my-agent","version":"0"}}}'

Un result con serverInfo.name: "flowie-exchange" significa che siete connessi. Un 404 significa che avete raggiunto un deployment più vecchio — segnalatecelo, perché è un bug dalla nostra parte, non un problema di configurazione dalla vostra.

Cosa significa beta

In concreto, perché possiate decidere su cosa costruire:

• Abbastanza stabile per costruirci sopra: gli endpoint, il modello di autenticazione, il bootstrap sandbox e l’URL dell’indice delle skill. Sono coperti dalla nostra politica di deprecazione come ogni altra parte dell’API.
• Ancora in movimento: i singoli nomi e argomenti degli strumenti, la composizione dell’insieme selezionato e il contenuto delle skill. Uno strumento rinominato rompe un prompt, non un compilatore: per questo annunciamo ogni modifica nel changelog — leggetelo prima di fissare qualcosa.
• Non ancora coperta: la CLI, in beta privata, che non porta alcuna promessa di compatibilità.
• Le modifiche incompatibili dell’API sottostante escono comunque solo in una nuova major, sotto un nuovo prefisso di URL. La beta non cambia questo.

State costruendo qualcosa su questo? Ditecelo — durante la beta è il modo più rapido per far rinominare uno strumento, correggere una skill o aggiungere una capacità mancante.