vibedasher-mcp

An MCP server that exposes the Vibedasher data engine — datasets, CSV upload + ETL, headless SQL query, and dashboard (viz) management — as tools a customer's AI (Claude Code, Cursor, ...) can drive directly.

This is the control plane (VD-601, PIVOT/PLAN.md EP-6). It wraps the published vibedasher Python SDK and calls only the public, metered /api/v1/* API.

Install: pip install vibedasher-mcp — live on PyPI since 2026-08-09, as are vibedasher (PyPI) and @vibedasher/client (npm).

The eject tools (VD-602) 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 (VD-301): 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 VD-203 RLS/alias-rewrite; SQL references only aliases.

Auth

API key only, via X-Api-Key (handled by the SDK's create_client). Set:

export VIBEDASHER_API_KEY=...           # mint via `POST /v1/api-keys` or the console
export VIBEDASHER_REGION=eu-central-1   # or us-east-1
# export VIBEDASHER_BASE_URL=...        # optional override (on-prem/staging)

The key is checked at startup: vibedasher-mcp refuses to start without it and prints what to do on stderr, so a key-less server never connects and never advertises tools it cannot serve. It is never logged or echoed in any 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        # (monorepo dev: also make `vibedasher` importable)
vibedasher-mcp                    # stdio MCP server
# or:  python -m vibedasher_mcp

MCP client config (Claude Code / Cursor):

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

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.