The open-source semantic model server for Malloy
Serve governed data models to applications, BI tools, and AI agents — over REST and MCP.
When an AI queries your database directly, it writes its own SQL — and gets it subtly wrong: the wrong join, an invented column, a fan-out that double-counts but still looks plausible. Publisher puts a Malloy semantic layer in front of your data, where measures, dimensions, and joins are defined once, correctly. Applications, BI tools, and AI agents compose queries against that model instead of writing raw SQL, so the numbers come back right by construction. Agents work through the sources the model defines — not your raw tables — and you decide exactly what each caller can see.
Point Publisher at your Malloy models and it serves them over a REST API and a single MCP endpoint.
npx @malloy-publisher/server --port 4000Open http://localhost:4000 and explore the bundled example packages —
storefront (a complete ecommerce model),
governed-analytics (access control), and
html-data-app (a no-build dashboard) —
all DuckDB-backed, no credentials required. Give the server a moment to report serving:
curl -s http://localhost:4000/api/v0/status | jq .operationalState # → "serving"This is the fast path to the "wow." Start the server, then connect any MCP-compatible agent to the MCP endpoint on port 4040:
claude mcp add --transport http malloy http://localhost:4040/mcpThen just ask, in plain English:
"Use Malloy to explore the storefront sales data and chart revenue by category."
The agent discovers what data exists (malloy_getContext), grounds itself in the real source, view,
and field names, runs the query (malloy_executeQuery), and returns an answer backed by your
semantic model. No schema spelunking, no hallucinated column names.
- Agents: this repo ships an AGENTS.md and a bundled skill library
(
skills/) that most AI coding hosts auto-discover. Start there. - Any MCP client (Cursor, VS Code, Codex, Claude Desktop): see docs/ai-agents.md for per-client config and the stdio bridge.
The MCP server is stateless and unauthenticated, and it can read any data your models connect to. Bind it to loopback (
--host 127.0.0.1) for local use, and put an authenticating gateway in front before exposing it more widely.
- Explore, no code. Build and drill into queries visually with Malloy Explorer — every action generates valid Malloy, so metrics stay correct even across joins.
- Answer questions with AI. Connect an agent over MCP and ask in plain English — see above and docs/ai-agents.md.
- Surface analytics your way. Explore and share with zero code in the Publisher App, or ship a no-build HTML data app that Publisher hosts inside a package.
- Build & validate models. Author Malloy models guided by the bundled skills, then
publish them for serving. Agents get the same loop over MCP:
malloy_compilechecks an edit and returns diagnostics without running it, andmalloy_reloadPackagerecompiles a package from disk so a new source or view is queryable by name, no restart. - Govern access. Givens are one runtime-parameter mechanism that powers filter
widgets, row-level access (which rows a caller sees), and
#(authorize)source gates (who can query). Separately, curate what is discoverable and queryable.
The docs/ folder is the reference hub — see its index. Highlights:
| Topic | Doc |
|---|---|
| Runnable example packages | examples/ (storefront · governed-analytics · html-data-app · data-app) |
| Connect an AI agent over MCP | docs/ai-agents.md |
| No-code visual query builder | docs/explorer.md |
| The Publisher App (navigation & features) | docs/publisher-app.md |
| Build a custom UI (no build step) | docs/html-data-apps.md |
| REST & MCP API overview | docs/api-overview.md |
| Runtime parameters & access control | givens (base) · row-level · authorize · discovery |
| Database connections | docs/connections.md |
| Deploy (npx / Docker / Compose) | docs/deployment.md |
| Docker runtime deep-dive (layout, env, tuning) | packages/server/README.docker.md |
| Configuration & tuning reference | docs/configuration.md |
| Theming (light/dark, palette) | docs/theming.md |
| Architecture & how it fits together | docs/architecture.md |
| Build & develop from a clone | docs/development.md |
The complete user guide also lives at docs.malloydata.dev.
Build and hack on Publisher from a clone with docs/development.md; contribution process and sign-off are in CONTRIBUTING.md.
- Join the Malloy Slack
- Report issues on GitHub