vibedasher-mcp

An MCP server that hands your coding agent (Claude Code, Codex, Cursor, Gemini) the tools to build and ship a dashboard on Vibedasher — the home for the dashboards your AI built.

Your agent writes the dashboard as React + SQL; Vibedasher hosts it at a URL behind your login, with per-viewer row filtering, embeds, refresh schedules, alerts and subscriptions — and ejects it into your own repo whenever you want the frontend back. Managed cloud (EU, Frankfurt) or self-hosted.

The whole loop is driven from here: datasets, CSV upload + ETL, SQL query, and dashboard (viz) creation, build and publish. It wraps the published vibedasher Python SDK and calls only the public, metered /api/v1/* API.

Install: pip install 'vibedasher-mcp>=0.6.0', then vibedasher login — no API key to mint. Live on PyPI since 2026-08-09, as are vibedasher (PyPI) and @vibedasher/client (npm).

The eject tools ship in this package, not separately: eject_viz, eject_viz_files, eject_instructions and get_viz_files are registered by register_eject_tools() in eject.py. They pull a viz's code plus an SDK-wiring manifest so your AI can recreate the dashboard natively in your stack.

Tools

Delivery: an ejected tree does not fit in one response

Measured against prod on 2026-08-18: eject_viz(1275) is 44 files / 517,351 characters (~129k tokens) and eject_viz(1282) is 45 files / 556,363 characters (~139k tokens). MCP clients cap a tool result, so the single-shot payload was either dropped outright by a strict client or ate the agent's entire context. Every eject response now carries a delivery block, and the three file tools take the same three parameters.

eject_viz(viz_id=1275, out_dir="/abs/path/to/app/dashboard")   # one call, whole tree on disk

out_dir resolves on the machine running the MCP server; with the standard stdio launch (command: vibedasher-mcp) that is your machine, because the client spawns the server as a local subprocess. Relative paths are refused, existing files are refused unless overwrite=True, and any path escaping out_dir aborts the write before a byte lands.

Paging is the fallback, not the goal: round trips do not reduce total tokens (the content still crosses the model), they only keep each individual response deliverable. Hand delivery.pendingPaths straight back to eject_viz_files(viz_id, paths=...) and repeat until it is empty. A response with a non-empty pendingPaths is a page, not a tree.

Override the budget per call with max_chars or globally with VIBEDASHER_MCP_MAX_RESPONSE_CHARS.

Three data lanes

Pick by what you will do with the rows:

run_query_to_file writes on the machine running the MCP server, which with the standard stdio launch is the agent's own machine (the client spawns the server as a local subprocess). It is refused over --http, where the path would resolve on the server's disk. Both lanes that return counts honour the backend's 100,000-row cap: truncated: true means the rows — in the response or in the file — are a prefix. Parquet output is deliberately not offered: the wasm lane already returns Parquet the server built, and pyarrow is a 40 MB wheel to install for one option.

run_query reuses the SDK's hand-written query() transport: the caller never sees inline-vs-presigned delivery, MessagePack, or retries — one call in, typed rows out. Each dataset id resolves server-side to that dataset's cleanSQLName alias under the RLS/alias-rewrite; SQL references only aliases.

Auth

Two lanes. The first one is the default because it asks nothing of you.

Sign in through your browser (first run)

pip install 'vibedasher-mcp>=0.6.0'   # `login` does not exist below 0.6.0
vibedasher login                      # opens a browser; approve; done

vibedasher login opens your browser, captures the authorization code on a loopback listener bound to 127.0.0.1, and stores a short-lived refresh token in your OS keyring (with a 0600 file fallback where no keyring is available). There is no key to mint, copy, paste or rotate, and nothing lands in a config file or your shell history. Later runs are silent until the session lapses, at which point login asks again. The refresh token is single-use and rotates on every refresh; if a rotated-away copy is ever presented again — someone read the keyring or the credentials file — the whole session is revoked on the spot and the next run asks you to login again.

Two companions: vibedasher whoami prints the account, user, region and the date you will be asked to sign in again; vibedasher logout revokes this machine's session and forgets it.

The MCP client block then carries no credential at all:

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

VIBEDASHER_REGION is optional here — login records the region the account actually lives in — but pinning it costs nothing and makes the shard explicit.

API key (CI, servers, non-interactive agents)

Anywhere a browser cannot open, an API key is still the answer. Mint one in the console (Settings → API keys) or via POST /v1/api-keys, and give it to the server as an environment variable:

export VIBEDASHER_API_KEY=...           # X-Api-Key, handled by the SDK's create_client
export VIBEDASHER_REGION=eu-central-1   # or us-east-1
# export VIBEDASHER_BASE_URL=...        # optional override (on-prem/staging)

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

An API key authenticates as the user who created it, has no expiry unless one is set, and is a bearer secret in plaintext on whatever disk holds that config. That is a fine trade for a build server and a poor one for your laptop — which is why it is the second lane and not the first.

Keeping the key out of your editor's config

claude mcp add -e VIBEDASHER_API_KEY=... writes the key, in plaintext, into the editor's own config file — which gets backed up, synced between machines, and occasionally pasted into a bug report. So the server also reads an env file, ~/.vibedasher-mcp.env, whenever the variable is absent from its environment:

printf 'VIBEDASHER_API_KEY=...\nVIBEDASHER_REGION=eu-central-1\n' > ~/.vibedasher-mcp.env
chmod 600 ~/.vibedasher-mcp.env

Then the editor config carries no secret at all:

{ "mcpServers": { "vibedasher": { "command": "vibedasher-mcp" } } }

Details worth knowing before you rely on it:

• The environment wins. A variable set in the env block is used and the file is not consulted for it, so an existing setup keeps behaving identically. whoami reports which of the two answered (credential.source is env:VIBEDASHER_API_KEY or file:<path>) — a precedence rule whose loser is silent is how a session ends up acting in an account nobody chose.
• Owner-only, enforced. A file readable by group or other is refused with the chmod to run, not quietly used: the whole point is that the config file it replaces was already owner-only.
• Four names only — VIBEDASHER_API_KEY, VIBEDASHER_REGION, VIBEDASHER_BASE_URL, VIBEDASHER_AUTH_URL. Anything else in the file is ignored rather than exported, and values are taken literally: no interpolation, no $(...). A credential store that evaluates its own contents would be worse than the config file it replaces.
• VIBEDASHER_MCP_ENV_FILE points at a different path.

Either way, the server checks before it serves

vibedasher-mcp resolves a credential at startup — VIBEDASHER_API_KEY first (from the environment, then from the env file), and a stored vibedasher login session only when no key is set. With neither, it refuses to start and prints what to do on stderr, so a credential-less server never connects and never advertises tools it cannot serve. Neither credential is ever logged or echoed in a tool result.

Metering

Every tool hits the public, metered endpoints (create_dataset is credit-gated; run_query is metered via the usage/credits event). The MCP adds no side channel and bypasses no metering.

Run

pip install 'vibedasher-mcp>=0.6.0'   # (monorepo dev: also make `vibedasher` importable)
vibedasher login                       # sign in once, in a browser
vibedasher-mcp                         # stdio MCP server
# or:  python -m vibedasher_mcp

Wiring Claude Code in one line, on a machine that has signed in:

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

Then ask your agent for something. It has 85 tools; a good first prompt is "run whoami, then list_datasets, and build me a dashboard from the most interesting one — verify with get_build_status and probe_viz before telling me it's done."

Two verifiers, two worlds, and they do not overlap:

render_probe walks the WHOLE dashboard, not one screenful: it scrolls the frame to the bottom in steps (re-settling after each one, so a lazily-mounted tile is counted and a permanently skeletal one still goes red) and, when the tree exposes the generated page control [data-selector="page"] [data-value], opens every page and sweeps each. Tiles are unioned by node identity, so a tile carrying three conventions is one tile and two conventions marking different tiles add up. tiles.covers states in one sentence what the count is a count OF — all pages fully scrolled, one page fully scrolled, or one viewport — and whatever it could not walk stays in notVerified. Pass scroll=False / traverse_pages=False to narrow it; the caveat comes back when you do.

render_probe needs a browser, so Playwright is an extra:

pip install 'vibedasher-mcp[render]>=0.6.0' && python -m playwright install chromium

Without it the tool returns checked: false and that install command. It never reports a pass it did not earn.

For the JSON mcpServers form of both lanes, see Auth.

A bare 403 {"message":"Forbidden"} is always the credential

The edge rejects a request before the application sees it, so its refusal body is one word and nothing else. That one word stands for three different mistakes, and the response cannot tell you which:

Two conclusions this response does not support, and both are the ones usually drawn from it:

• It is not a path problem. With an accepted credential, an unknown path answers 404 and names the path in the body. A bare Forbidden never means the URL was wrong.
• It is not a permissions problem. Roles and resource access are decided by the application, which answers with a reason. The edge only ever asks whether a credential is valid, so a bare Forbidden is never "ask your human for access".

The single most common first-contact mistake is the second row: Authorization: Bearer <key> returns 403 on every route, including plain reads, with a perfectly good key.

Fix the header first, then read the body — once a credential is accepted, the API distinguishes all four conditions on its own.

Development

The package depends on the sibling SDK at ../sdk/py. Tests wire that path automatically (tests/conftest.py), so from packages/mcp:

python -m pytest tests/ -q

Note: fastmcp is a client-side dependency of this standalone package; it is not bundled into the API Lambdas, so the export_requirements.py step in the root CLAUDE.md does not apply here.