Skip to main content

Build with your agent (MCP)

This is the core workflow: the dashboard is built in your own harness — Claude Code, Codex, Cursor, any MCP client — and everything it depends on is maintained in Vibedasher. You don't build inside our app. Your agent works locally, and the vibedasher-mcp server gives it tools onto the maintained platform — datasets, the query engine, dashboard drafts and builds, publishing, sharing, access rights — so the stateful half (connections, datasets, pipelines, refreshes, governance, hosting) stays where it's maintained and governed, while the dashboard code stays in your agent's hands.

Know this before you write a line of it

What gets hosted is a client-rendered bundle. Your dashboard is React that runs in the visitor's browser over data served by SQL. None of your server code executes here — no API routes, no server-side rendering, no loaders, no background workers — so a server-rendered framework cannot be hosted as it stands: Next.js on either router, Remix, SvelteKit, Astro, Nuxt. There is also no npm install at build time; libraries come from a pinned list, and React is the only framework on it.

That stack is not refused, it is routed. Two doors, both open: keep your own server and pull this account's data into it with the SDK the install already gave you, or build the dashboard here and eject it to host yourself. Either way the connections, datasets, refreshes, governance and query engine stay maintained on this side.

Already have a tree? check_viz_tree(src_dir=<absolute path>) answers this statically, against your actual files, before you spend a build.

Install and sign in​

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

vibedasher login opens your browser, you approve the session, and you're done. The refresh token is written to your OS keyring — or, on a machine with no keyring backend, to a 0600 file under ~/.vibedasher/. No key to mint, copy into a config file, or rotate. The login subcommand needs 0.6.0 or later; earlier releases don't have it.

Two more subcommands are all there is:

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

By default login signs you into eu-central-1; pass --region for another region, and --timeout to change how long it waits for the callback (180 s).

If your terminal has no browser it can launch — WSL, a bare X-less desktop session, a terminal with no default handler — use vibedasher login --no-browser. It prints the URL instead of opening it, and waits for the same callback. Note the callback listener binds 127.0.0.1 on a port the OS picks at connect time, so the browser you paste the URL into has to be on the same machine. Signing in from a laptop for a remote box is not a lane login supports — for a machine you only reach over SSH, use an API key (below).

Then register the server. With Claude Code:

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

Or in any MCP client config:

{
  "mcpServers": {
    "vibedasher": {
      "command": "vibedasher-mcp",
      "env": { "VIBEDASHER_REGION": "eu-central-1" }
    }
  }
}

Note vibedasher-mcp is the server entry point your MCP client launches; vibedasher is the CLI you run yourself. The server picks up the session vibedasher login stored — there is no credential in the config block.

The server talks only to the public, metered API — the same surface as the SDKs. Nothing side-channel, and no credential is ever echoed in tool results.

Headless and CI — use an API key​

A build runner, a cron box, a container: nowhere for a browser to open, and nobody to click approve. There, authenticate with an API key instead. Mint one from the app at cloud.vibedasher.com (Settings → API keys) — key creation is session-only, so it is a browser action, not an API call; see Authentication — and put it in the server's env block:

{
  "mcpServers": {
    "vibedasher": {
      "command": "vibedasher-mcp",
      "env": {
        "VIBEDASHER_API_KEY": "<your-api-key>",
        "VIBEDASHER_REGION": "eu-central-1"
      }
    }
  }
}

VIBEDASHER_API_KEY takes precedence when it is set: the server uses the key and ignores any stored login session. Treat the key like a password — an environment variable or a secret store, never source control. On your own machine, prefer vibedasher login; there is then no long-lived secret on disk to leak or rotate.

The loop your agent runs​

Everything below is your agent building the dashboard — the platform state it builds against (connections, datasets, refreshes, governance) is set up once and maintained in Vibedasher, so every iteration of the loop finds it already there.

  1. Get data in — upload_dataset_from_file(name, csv_path) for a file on disk (upload_dataset takes the CSV inline instead, which costs tokens for every row), or create_dataset_from_connection against a connected data source. Every dataset gets a cleanSQLName alias — that alias is the table name in SQL, never a physical table name.
  2. Explore — run_query(sql, dataset_ids): read-only SELECT across datasets, typed columns and rows back.
  3. Create & build — create_viz(name, dataset_ids), then push_viz_files(viz_id, files) with a root App.tsx, then build_viz → get_build_status(build_id) until the bundle compiles. Already have a React tree? check_viz_tree(src_dir=...) names every edit it needs first, statically, without spending a build.
  4. Publish — publish_viz(viz_id) promotes the draft to the version viewers get, and share_viz(viz_id) returns the link to hand out. build_viz on its own does not publish.
  5. Verify — render_probe(viz_id) opens the published dashboard in a real browser and reports what actually painted: how many tiles rendered, the headline numbers read back verbatim, and any console error. A green build means the code compiled — not that the chart shows what its title claims, and a chart that never received data leaves a full-size single-colour canvas that every count-based check passes on.
  6. Iterate — eject_viz to pull the full React source, edit locally, push_viz_files to commit back to the draft branch, rebuild, republish.

Your agent also has tools for folders, groups, users, and access rights (grant_access / revoke_access), so governance is scriptable too — see Publish and share.

Eject — the code stays yours​

Publishing to Vibedasher is the normal end of the loop — that's what keeps the dashboard hosted, governed, and wired to maintained data. But the code itself is plain React and SQL and it stays yours: eject_viz hands your agent the complete runnable source tree (components, package.json, Tailwind config) plus a wiring manifest, and eject_instructions explains how to rebuild it natively in your own app — queries running through the SDK against your Vibedasher datasets, hosting entirely on your side. Large trees are delivered to disk (out_dir=...) or paged; follow delivery.pendingPaths until it's empty before treating the tree as complete.

One choice inside that is worth making on purpose, because it is the half you cannot change afterwards. An ejected dashboard on a public + published viz ships with a credential-free lane: it downloads a Parquet extract and runs every query in the visitor's browser, with no key, no token and no backend of your own. That also means every visitor gets every row of the dataset, and no viewer can be shown fewer rows than another — see Who can see what for the two wirings that can scope a viewer, and decide between them before you build.

The full story — the three eject calls, the paging contract, and the two live prop generations — is in Eject your dashboard.

Next​

The app at cloud.vibedasher.com works on the same dashboards and drafts your agent does, so a person can review in the UI and publish from there — but the harness loop above is the path we build for and document.