# Construa com seu agente (MCP)

Este é o fluxo de trabalho principal: **o painel é construído no seu próprio agente de IA — Claude Code, Codex, Cursor, qualquer cliente MCP — e tudo aquilo de que ele depende é mantido na Vibedasher.** Você não constrói dentro do nosso app. Seu agente trabalha localmente, e o servidor **`vibedasher-mcp`** lhe dá ferramentas sobre a plataforma mantida — conjuntos de dados, o mecanismo de consultas, rascunhos e builds de painéis, publicação, compartilhamento, direitos de acesso — de modo que a metade stateful (conexões, conjuntos de dados, pipelines, atualizações, governança, hospedagem) permanece onde é mantida e governada, enquanto o código do painel permanece nas mãos do seu agente.

Saiba disto antes de escrever uma linha

**O que é hospedado é um bundle renderizado no cliente.** Seu painel é React que roda no navegador do visitante sobre dados servidos por SQL. Nada do seu código de servidor é executado aqui — sem rotas de API, sem renderização no servidor, sem loaders, sem workers em segundo plano — então um framework com renderização no servidor não pode ser hospedado como está: Next.js em qualquer um dos dois routers, Remix, SvelteKit, Astro, Nuxt. Também não há `npm install` em tempo de build; as bibliotecas vêm de uma lista fixada, e React é o único framework nela.

Essa pilha não é recusada, ela é **redirecionada**. Duas portas, as duas abertas: mantenha seu próprio servidor e traga para ele os dados desta conta com o SDK que a instalação já lhe deu, ou construa o painel aqui e [ejete-o](/pt-BR/guides/eject-your-dashboard.md) para hospedar você mesmo. Nos dois casos as conexões, os conjuntos de dados, as atualizações, a governança e o mecanismo de consultas continuam mantidos deste lado.

Já tem uma árvore? `check_viz_tree(src_dir=<absolute path>)` responde a isso estaticamente, contra os seus arquivos reais, antes de gastar um build.

## Instale e faça login[​](#instale-e-faça-login "Link direto para Instale e faça login")

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

vibedasher login
```

`vibedasher login` abre seu navegador, você aprova a sessão e pronto. O token de atualização é gravado no keyring do seu sistema operacional — ou, em uma máquina sem backend de keyring, em um arquivo `0600` em `~/.vibedasher/`. Nenhuma chave para gerar, copiar em um arquivo de configuração ou rotacionar. O subcomando `login` precisa da versão **0.6.0 ou superior**; versões anteriores não o possuem.

Só existem mais dois subcomandos:

```
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
```

Por padrão, `login` faz login em `eu-central-1`; passe `--region` para outra região, e `--timeout` para mudar quanto tempo ele espera pelo callback (180 s).

Se o seu terminal não tem um navegador que possa abrir — WSL, uma sessão de desktop sem X, um terminal sem handler padrão — use `vibedasher login --no-browser`. Ele imprime a URL em vez de abri-la, e espera pelo mesmo callback. Note que o listener do callback se vincula a `127.0.0.1` em uma porta que o sistema operacional escolhe no momento da conexão, então o navegador onde você colar a URL precisa estar na **mesma máquina**. Fazer login em um notebook para uma máquina *remota* não é um caminho que o `login` suporta — para uma máquina que você só acessa via SSH, use uma chave de API (abaixo).

Em seguida, registre o servidor. Com o Claude Code:

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

Ou em qualquer configuração de cliente MCP:

```
{

  "mcpServers": {

    "vibedasher": {

      "command": "vibedasher-mcp",

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

    }

  }

}
```

Note que `vibedasher-mcp` é o ponto de entrada do **servidor** que seu cliente MCP inicia; `vibedasher` é a CLI que você mesmo executa. O servidor usa a sessão que o `vibedasher login` armazenou — não há credencial no bloco de configuração.

O servidor conversa apenas com a API pública e medida — a mesma superfície dos [SDKs](/pt-BR/api/sdks.md). Nada de canal lateral, e nenhuma credencial é jamais exibida nos resultados das ferramentas.

### Headless e CI — use uma chave de API[​](#headless-and-ci--use-an-api-key "Link direto para Headless e CI — use uma chave de API")

Um runner de build, uma máquina de cron, um container: nenhum lugar para um navegador abrir, e ninguém para clicar em aprovar. Nesses casos, autentique-se com uma **chave de API**. Gere uma no app em [cloud.vibedasher.com](https://cloud.vibedasher.com) (Configurações → Chaves de API) — a criação de chave é somente por sessão, então é uma ação de navegador, não uma chamada de API; veja [Autenticação](/pt-BR/api/authentication.md) — e coloque-a no bloco `env` do servidor:

```
{

  "mcpServers": {

    "vibedasher": {

      "command": "vibedasher-mcp",

      "env": {

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

        "VIBEDASHER_REGION": "eu-central-1"

      }

    }

  }

}
```

`VIBEDASHER_API_KEY` tem precedência quando está definida: o servidor usa a chave e ignora qualquer sessão de login armazenada. Trate a chave como uma senha — uma variável de ambiente ou um cofre de segredos, nunca controle de versão. Na sua própria máquina, prefira o `vibedasher login`; assim não há segredo de longa duração em disco para vazar ou rotacionar.

## O ciclo que seu agente executa[​](#o-ciclo-que-seu-agente-executa "Link direto para O ciclo que seu agente executa")

Tudo abaixo é o seu agente construindo o *painel* — o estado da plataforma contra o qual ele constrói (conexões, conjuntos de dados, atualizações, governança) é configurado uma vez e mantido na Vibedasher, então cada iteração do ciclo o encontra já pronto.

1. **Traga os dados** — `upload_dataset_from_file(name, csv_path)` para um arquivo em disco (`upload_dataset` recebe o CSV embutido em vez disso, o que custa tokens por cada linha), ou `create_dataset_from_connection` contra uma [fonte de dados conectada](/pt-BR/guides/connect-a-data-source.md). Todo conjunto de dados recebe um alias `cleanSQLName` — esse alias é o nome da tabela em SQL, nunca o nome de uma tabela física.
2. **Explore** — `run_query(sql, dataset_ids)`: um SELECT somente leitura entre conjuntos de dados, retornando colunas e linhas tipadas.
3. **Crie e construa** — `create_viz(name, dataset_ids)`, depois `push_viz_files(viz_id, files)` com um `App.tsx` na raiz, depois `build_viz` → `get_build_status(build_id)` até o bundle compilar. Já tem uma árvore React? `check_viz_tree(src_dir=...)` nomeia primeiro cada alteração necessária, estaticamente, sem gastar um build.
4. **Publique** — `publish_viz(viz_id)` promove o rascunho para a versão que os visualizadores recebem, e `share_viz(viz_id)` retorna o link para compartilhar. `build_viz` por si só **não** publica.
5. **Verifique** — `render_probe(viz_id)` abre o painel publicado em um navegador real e relata o que realmente foi pintado: quantos tiles renderizaram, os números principais relidos literalmente, e qualquer erro de console. Um build verde significa que o código compilou — não que o gráfico mostra o que seu título afirma, e um gráfico que nunca recebeu dados deixa um canvas de cor única em tamanho cheio que toda verificação baseada em contagem aprova.
6. **Itere** — `eject_viz` para extrair o código-fonte React completo, edite localmente, `push_viz_files` para enviar de volta ao branch de rascunho, reconstrua, republique.

Seu agente também tem ferramentas para pastas, grupos, usuários e direitos de acesso (`grant_access` / `revoke_access`), então a governança também é scriptável — veja [Publique e compartilhe](/pt-BR/guides/publish-and-share.md).

## Ejetar — o código continua seu[​](#eject--the-code-stays-yours "Link direto para Ejetar — o código continua seu")

Publicar na Vibedasher é o fim normal do ciclo — é isso que mantém o painel hospedado, governado e conectado a dados mantidos. Mas o código em si é React e SQL puros e continua seu: `eject_viz` entrega ao seu agente a árvore de código-fonte completa e executável (componentes, `package.json`, configuração do Tailwind) além de um manifesto de conexões, e `eject_instructions` explica como reconstruí-lo nativamente no seu próprio app — consultas rodando através do SDK contra seus conjuntos de dados da Vibedasher, com hospedagem inteiramente do seu lado. Árvores grandes são entregues em disco (`out_dir=...`) ou paginadas; siga `delivery.pendingPaths` até ficar vazio antes de tratar a árvore como completa.

Uma escolha dentro disso vale a pena ser feita de propósito, porque é a metade que você não consegue mudar depois. Um painel ejetado a partir de uma visualização **pública e publicada** vem com uma via sem credenciais: ele baixa um extrato Parquet e executa toda consulta no navegador do visitante, sem chave, sem token e sem backend seu. Isso também significa que todo visitante recebe todas as linhas do conjunto de dados, e que nenhum visualizador pode ver menos linhas do que outro — veja [Quem pode ver o quê](/pt-BR/guides/who-can-see-what.md#row-level-filtering-the-embed-lane-and-only-the-embed-lane) para as duas configurações que *podem* delimitar um visualizador, e decida entre elas antes de construir.

A história completa — as três chamadas de ejeção, o contrato de paginação, e as duas gerações de props ainda vivas — está em **[Ejete seu painel](/pt-BR/guides/eject-your-dashboard.md)**.

## A seguir[​](#a-seguir "Link direto para A seguir")

* **[A via de consulta wasm](/pt-BR/guides/the-wasm-query-lane.md)** — a via de dados sem credenciais em detalhe, e o que ela sacrifica.
* **[Ejete seu painel](/pt-BR/guides/eject-your-dashboard.md)** — tirar o código de dentro, e religar os dados.

O app em [cloud.vibedasher.com](https://cloud.vibedasher.com) trabalha sobre os mesmos painéis e rascunhos que o seu agente, então uma pessoa pode revisar na interface e publicar de lá — mas o ciclo do agente acima é o caminho para o qual construímos e que documentamos.