# Crea con il tuo agente (MCP)

Questo è il flusso di lavoro principale: **la dashboard viene creata nel tuo harness — Claude Code, Codex, Cursor, qualsiasi client MCP — e tutto ciò da cui dipende è gestito in Vibedasher.** Non crei nulla dentro la nostra app. Il tuo agente lavora in locale, e il server **`vibedasher-mcp`** gli fornisce strumenti sulla piattaforma gestita — dataset, motore di query, bozze e build delle dashboard, pubblicazione, condivisione, diritti di accesso — così la metà stateful (connessioni, dataset, pipeline, aggiornamenti, governance, hosting) resta dove viene gestita e governata, mentre il codice della dashboard resta nelle mani del tuo agente.

Da sapere prima di scriverne una riga

**Quello che viene ospitato è un bundle renderizzato lato client.** La tua dashboard è React che gira nel browser del visitatore su dati serviti via SQL. Nulla del tuo codice server viene eseguito qui — nessuna route API, nessun rendering lato server, nessun loader, nessun worker in background — quindi un framework con rendering lato server non può essere ospitato così com'è: Next.js con entrambi i router, Remix, SvelteKit, Astro, Nuxt. Non c'è nemmeno `npm install` al momento della build; le librerie arrivano da un elenco fissato, e React è l'unico framework che vi compare.

Quello stack non viene rifiutato, viene **instradato**. Due porte, entrambe aperte: tieni il tuo server e portaci i dati di questo account con l'SDK che l'installazione ti ha già dato, oppure crea la dashboard qui e [espellila](/it/guides/eject-your-dashboard.md) per ospitarla tu. In entrambi i casi connessioni, dataset, aggiornamenti, governance e motore di query restano gestiti da questo lato.

Hai già un albero? `check_viz_tree(src_dir=<absolute path>)` risponde a questa domanda staticamente, sui tuoi file reali, prima di spendere una build.

## Installa e accedi[​](#installa-e-accedi "Link diretto a Installa e accedi")

```
pip install 'vibedasher-mcp>=0.6.0'

vibedasher login
```

`vibedasher login` apre il browser, tu approvi la sessione e hai finito. Il token di aggiornamento viene scritto nel keyring del tuo sistema operativo — oppure, su una macchina senza un backend keyring, in un file `0600` sotto `~/.vibedasher/`. Nessuna chiave da generare, copiare in un file di configurazione o ruotare. Il sottocomando `login` richiede **0.6.0 o versioni successive**; le release precedenti non lo hanno.

Ci sono solo altri due sottocomandi:

```
vibedasher whoami    # the signed-in account, user and region, and when re-consent falls due

vibedasher logout    # revoke this machine's session and forget it
```

Per impostazione predefinita `login` ti fa accedere a `eu-central-1`; passa `--region` per un'altra regione, e `--timeout` per cambiare quanto tempo attende il callback (180 s).

Se il tuo terminale non ha un browser che può aprire — WSL, una sessione desktop senza X, un terminale senza handler predefinito — usa `vibedasher login --no-browser`. Stampa l'URL invece di aprirlo, e attende lo stesso callback. Nota che il listener del callback si lega a `127.0.0.1` su una porta scelta dal sistema operativo al momento della connessione, quindi il browser in cui incolli l'URL deve trovarsi sulla **stessa macchina**. Accedere da un laptop per una macchina *remota* non è una modalità supportata da `login` — per una macchina raggiungibile solo via SSH, usa una chiave API (sotto).

Poi registra il server. Con Claude Code:

```
claude mcp add vibedasher --env VIBEDASHER_REGION=eu-central-1 -- vibedasher-mcp
```

Oppure in qualsiasi configurazione client MCP:

```
{

  "mcpServers": {

    "vibedasher": {

      "command": "vibedasher-mcp",

      "env": { "VIBEDASHER_REGION": "eu-central-1" }

    }

  }

}
```

Nota che `vibedasher-mcp` è il punto di ingresso del **server** che il tuo client MCP avvia; `vibedasher` è la CLI che esegui tu stesso. Il server recupera la sessione salvata da `vibedasher login` — non c'è alcuna credenziale nel blocco di configurazione.

Il server parla solo con l'API pubblica e a consumo misurato — la stessa superficie degli [SDK](/it/api/sdks.md). Niente canali laterali, e nessuna credenziale viene mai restituita nei risultati degli strumenti.

### Headless e CI — usa una chiave API[​](#headless-and-ci--use-an-api-key "Link diretto a Headless e CI — usa una chiave API")

Un build runner, una macchina cron, un container: nessun posto dove aprire un browser, e nessuno che possa cliccare approva. Lì, autenticati invece con una **chiave API**. Generane una dall'app su [cloud.vibedasher.com](https://cloud.vibedasher.com) (Impostazioni → Chiavi API) — la creazione della chiave è solo di sessione, quindi è un'azione da browser, non una chiamata API; vedi [Autenticazione](/it/api/authentication.md) — e mettila nel blocco env del server:

```
{

  "mcpServers": {

    "vibedasher": {

      "command": "vibedasher-mcp",

      "env": {

        "VIBEDASHER_API_KEY": "<your-api-key>",

        "VIBEDASHER_REGION": "eu-central-1"

      }

    }

  }

}
```

`VIBEDASHER_API_KEY` ha la precedenza quando è impostata: il server usa la chiave e ignora qualsiasi sessione di accesso salvata. Tratta la chiave come una password — una variabile d'ambiente o un secret store, mai il controllo versione. Sulla tua macchina, preferisci `vibedasher login`; in quel caso non c'è alcun segreto a lungo termine su disco da far trapelare o ruotare.

## Il ciclo che il tuo agente esegue[​](#il-ciclo-che-il-tuo-agente-esegue "Link diretto a Il ciclo che il tuo agente esegue")

Tutto quanto segue è il tuo agente che costruisce la *dashboard* — lo stato della piattaforma su cui costruisce (connessioni, dataset, aggiornamenti, governance) è configurato una volta e mantenuto in Vibedasher, quindi ogni iterazione del ciclo lo trova già lì.

1. **Fai entrare i dati** — `upload_dataset_from_file(name, csv_path)` per un file su disco (`upload_dataset` prende invece il CSV inline, che costa token per ogni riga), oppure `create_dataset_from_connection` su una [fonte dati connessa](/it/guides/connect-a-data-source.md). Ogni dataset ottiene un alias `cleanSQLName` — quell'alias è il nome della tabella in SQL, mai un nome di tabella fisica.
2. **Esplora** — `run_query(sql, dataset_ids)`: SELECT in sola lettura sui dataset, con colonne e righe tipizzate in risposta.
3. **Crea e costruisci** — `create_viz(name, dataset_ids)`, poi `push_viz_files(viz_id, files)` con un `App.tsx` nella radice, poi `build_viz` → `get_build_status(build_id)` finché il bundle non compila. Hai già un albero React? `check_viz_tree(src_dir=...)` nomina prima ogni modifica necessaria, staticamente, senza spendere una build.
4. **Pubblica** — `publish_viz(viz_id)` promuove la bozza alla versione che i visualizzatori ottengono, e `share_viz(viz_id)` restituisce il link da condividere. `build_viz` da solo **non** pubblica.
5. **Verifica** — `render_probe(viz_id)` apre la dashboard pubblicata in un browser reale e riporta cosa è stato effettivamente disegnato: quanti tile sono stati renderizzati, i numeri principali riletti alla lettera, e qualsiasi errore di console. Una build verde significa che il codice ha compilato — non che il grafico mostri ciò che il suo titolo afferma, e un grafico che non ha mai ricevuto dati lascia un canvas monocromatico a dimensione piena su cui ogni controllo basato sui conteggi passa.
6. **Itera** — `eject_viz` per estrarre l'intero sorgente React, modificalo in locale, `push_viz_files` per fare commit di nuovo sul branch della bozza, ricostruisci, ripubblica.

Il tuo agente ha anche strumenti per cartelle, gruppi, utenti e diritti di accesso (`grant_access` / `revoke_access`), quindi anche la governance è scriptabile — vedi [Pubblica e condividi](/it/guides/publish-and-share.md).

## Espelli — il codice resta tuo[​](#eject--the-code-stays-yours "Link diretto a Espelli — il codice resta tuo")

Pubblicare su Vibedasher è la normale fine del ciclo — è ciò che mantiene la dashboard ospitata, governata e collegata ai dati gestiti. Ma il codice in sé è semplice React e SQL e resta tuo: `eject_viz` consegna al tuo agente l'intero albero dei sorgenti eseguibile (componenti, `package.json`, configurazione Tailwind) più un manifest di cablaggio, e `eject_instructions` spiega come ricostruirlo nativamente nella tua app — query eseguite tramite l'SDK sui tuoi dataset Vibedasher, hosting interamente dal tuo lato. Gli alberi di grandi dimensioni vengono consegnati su disco (`out_dir=...`) o paginati; segui `delivery.pendingPaths` finché non è vuoto prima di considerare l'albero completo.

Una scelta dentro tutto questo vale la pena farla di proposito, perché è la metà che non puoi più cambiare in seguito. Una dashboard espulsa da una visualizzazione **pubblica e pubblicata** arriva con una corsia senza credenziali: scarica un estratto Parquet ed esegue ogni query nel browser del visitatore, senza chiave, senza token e senza un backend tuo. Questo significa anche che ogni visitatore ottiene tutte le righe del dataset, e che a nessun visualizzatore possono essere mostrate meno righe che a un altro — vedi [Chi può vedere cosa](/it/guides/who-can-see-what.md#row-level-filtering-the-embed-lane-and-only-the-embed-lane) per le due configurazioni che *possono* restringere un visualizzatore, e scegli tra esse prima di costruire.

La storia completa — le tre chiamate di espulsione, il contratto di paginazione e le due generazioni di prop attive — è in **[Espelli la tua dashboard](/it/guides/eject-your-dashboard.md)**.

## Prossimi passi[​](#prossimi-passi "Link diretto a Prossimi passi")

* **[La corsia di query wasm](/it/guides/the-wasm-query-lane.md)** — la corsia dati senza credenziali in dettaglio, e cosa rinuncia in cambio.
* **[Espelli la tua dashboard](/it/guides/eject-your-dashboard.md)** — portare fuori il codice, e ricollegare i dati.

L'app su [cloud.vibedasher.com](https://cloud.vibedasher.com) lavora sulle stesse dashboard e bozze del tuo agente, quindi una persona può rivedere nell'interfaccia e pubblicare da lì — ma il ciclo dell'harness descritto sopra è il percorso per cui sviluppiamo e che documentiamo.