Malloy Publisher

The open-source semantic model server for Malloy
Serve governed data models to applications, BI tools, and AI agents — over REST and MCP.

_{A 60-second walkthrough — model in your IDE with the Malloy skills, serve with Publisher, build a data app, materialize on a schedule, and analyze. Watch the video for playback controls.}

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.

Quick start

npx @malloy-publisher/server --port 4000

Open 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"

A first npx run fetches the example packages from GitHub and reports its download progress on stderr. When the server is ready it prints a single line, also to stderr, that scripts can wait for instead of polling:

PUBLISHER_READY url=http://localhost:4000 mcp=http://localhost:4040 environments=1 packages=3 load_errors=0

load_errors counts configured packages and environments that failed to load. When it is not 0, /api/v0/status names each one under .loadErrors. The url= host reads localhost when the server binds every interface (the default); a configured --host shows as itself. If initialization fails, a PUBLISHER_INIT_FAILED line is printed in its place; a startup failure outside initialization, like a port already in use, crashes without either token.

Point your agent at it

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/mcp

Then 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 server, MCP and REST alike, 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.

No MCP client, or an agent running unattended that started the server itself? The same loop is available over plain REST:

curl -s -X POST \
  http://localhost:4000/api/v0/environments/examples/packages/storefront/models/storefront.malloy/query \
  -H 'content-type: application/json' \
  -d '{"query":"run: order_items -> by_category","compactJson":true}' | jq -r .result

A package is just a directory with a publisher.json and a .malloy model; docs/packages.md is the format reference. The running server serves its full OpenAPI spec at http://localhost:4000/api-doc.yaml, and docs/ai-agents.md covers agents in both modes, MCP and REST.

What you can do

• 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_compile checks an edit and returns diagnostics without running it, and malloy_reloadPackage recompiles 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.
• Materialize for cost & speed. Persist an expensive source into a table with #@ persist, then rebuild it on demand or on a cron with the opt-in standalone scheduler — see docs/materialization.md and the malloy-pub schedule / list materialization CLI.

Documentation

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)
Architecture & how it fits together	docs/architecture.md
REST & MCP API overview	docs/api-overview.md
The package format (publisher.json, models, data)	docs/packages.md
The Publisher App (navigation & features)	docs/publisher-app.md
No-code visual query builder	docs/explorer.md
Connect an AI agent (MCP, or REST when unattended)	docs/ai-agents.md
Build a custom UI (no build step)	docs/html-data-apps.md
Runtime parameters & access control	givens (base) · row-level · authorize · discovery
Deploy (npx / Docker / Compose)	docs/deployment.md
Database connections	docs/connections.md
Materialization & scheduling	docs/materialization.md
Docker runtime deep-dive (layout, env, tuning)	packages/server/README.docker.md
Theming (light/dark, palette)	docs/theming.md
Configuration & tuning reference	docs/configuration.md
Build & develop from a clone	docs/development.md

The complete user guide also lives at docs.malloydata.dev.

Contributing

Build and hack on Publisher from a clone with docs/development.md; contribution process and sign-off are in CONTRIBUTING.md.

Community

• Join the Malloy Slack
• Report issues on GitHub