Duckboard

Websites can be built for agents, not merely made accessible to them.

Agent-first software often starts outside the web platform: an MCP server, MCP App, CLI, or skill. WebMCP turns that assumption around. A page can expose a compact programmatic interface to an agent while retaining everything the browser already provides—Wasm, workers, local files, network access, graphics, and a human-visible canvas. For some workflows, the website itself can replace a separate integration.

Duckboard demonstrates the idea with two tools. An agent uses DuckDB-Wasm to load, join, and aggregate data, then carries the result into a full-screen visualization. Everything runs in the browser.

Built for the Codex hackathon, Duckboard is an invitation to push WebMCP beyond form automation. Treat the agent as a first-class user of the web, design the site around programmatic tool calling, and see what the web platform can become when the agent gets an interface of its own.

Run it

Requirements: Node.js 22.12 or newer, pnpm 10 or newer, and a browser or agent host that exposes native document.modelContext.

pnpm install
pnpm dev

Open the printed URL in Codex's browser or another WebMCP-capable host. Duckboard intentionally does not load a polyfill.

Try it

Give the page to Codex, then ask:

Use DuckDB to join the public 2024 flight Parquet data with the public airport CSV, find the busiest routes and their average arrival delay, then render a responsive full-screen visualization.

The matching query is checked in at examples/flights.sql. Remote origins must permit browser requests through CORS.

Once the app has been cached, try this offline:

Use DuckDB to generate 90 days of synthetic product activity, summarize signups and retention by week, then render a responsive dashboard with the preloaded Sigvelo components.

The two tools

Tool	Input	Effect
duckdb_sql	DuckDB SQL	Loads, joins, transforms, or queries data in the tab-local DuckDB session and returns structured rows.
render_html	HTML fragment or document	Replaces the canvas with a fresh sandboxed visualization.

The descriptions registered with these tools contain the working context an agent needs: DuckDB references, available data sources, Sigvelo elements and tokens, sandbox behavior, and links to the component manifests.

How it works

The agent explicitly carries selected query results into the HTML it renders:

local files + remote CSV / JSON / Parquet
                    |
                    v
              duckdb_sql
                    |
             structured rows
                    |
                    v
              render_html
                    |
                    v
         fresh opaque-origin iframe

Large scans, joins, filters, and aggregations stay in DuckDB. Only the result chosen by the agent is embedded in the rendered document. The iframe receives no database connection, file handle, host storage, or WebMCP capability.

The renderer accepts inline scripts and pinned HTTPS dependencies such as D3 from esm.sh. The iframe protects the host origin and its capabilities; authored scripts can still make HTTPS requests and consume CPU.

Data sources

• A person can select or drop CSV, JSON, Parquet, Arrow, or IPC files. Duckboard registers them under local/* through DuckDB's browser file API.
• DuckDB can query supported public HTTPS resources directly when the origin permits CORS.
• The stateful session can create tables and views across tool calls.
• Local and remote relations participate in the same SQL joins.

Native file pickers require a user gesture. An agent can query a selected file, but it cannot silently open the picker or acquire a new local file handle.

Code map

File	Owns
src/duckdb.ts	DuckDB-Wasm initialization, its browser-selected worker and engine, the tab-local connection, file registration, and Arrow-to-JSON conversion.
src/tools.ts	The two native WebMCP contracts, typed by @mcp-b/webmcp-types.
src/main.ts	The visible shell, source history, local-file gesture, and iframe handoff.
public/sandbox.html	The isolated renderer and its preloaded Sigvelo components.

There is no application framework, backend, query editor, dashboard builder, sharing layer, or templating language. Vite builds the static app, Vite PWA provides the installable shell, and Cloudflare serves it.

Build

pnpm build
pnpm preview

pnpm deploy builds and deploys with the checked-in Cloudflare configuration. Workbox precaches the application shell and pinned esm.sh entrypoints, then caches the browser-selected DuckDB-Wasm runtime, loaded extensions, and transitive esm.sh modules as they are used. Once those caches are warm, SQL, synthetic data, and reselected local files work offline. Rendering a new visualization still needs a connection because the opaque sandbox loads Sigvelo and agent-authored libraries directly from HTTPS CDNs.

License

MIT