Getting started with Malloy Publisher

Goal: go from "connected" to a correct, grounded answer without guessing any names.

0. Confirm the tools are reachable

At minimum you need malloy_getContext, malloy_executeQuery, and malloy_searchDocs. Authoring a model also needs malloy_compile and malloy_reloadPackage (see section 4); an older Publisher may not serve those two.

If none of the tools are there, either the server is not running or your client connected before it was. Start the server (npx @malloy-publisher/server --port 4000, or bun run build && bun run start from a clone) and wait until curl -s http://localhost:4000/api/v0/status reports operationalState: serving.

If there is no Publisher workspace here at all, and the user wants to work with data of their own rather than the bundled examples, npm create @malloy-publisher/malloy-package@latest <name> scaffolds one: the package and a starter model, registered so the server actually serves it, plus the start script, the MCP config and these skills. Keep the @latest when you type it: npm create resolves through npm's npx cache and an unversioned name is satisfied by any copy already there, so on a machine that has scaffolded before npm never asks the registry and you get an old scaffolder pinning an old server, with nothing to say so. Run bare, it comes with a small sample dataset, so there is something to query straight away. In a fresh directory npm start then runs the pinned server against the package in watch mode; if the directory already had a package.json the scaffolder leaves it alone and adds no script, printing the equivalent npx command to use instead. Where you run it matters: only the package lands in <name>/, and the workspace files, the agent instructions and the MCP config among them, are written to the current directory. Run it here if this directory is empty or is meant to become the workspace. If it already holds other work, scaffold into a new directory instead (mkdir my-data && cd my-data), because agent config is discovered by walking up, so writing those files here changes what every session beneath this directory inherits. Seed the starter model from a local file with npm create @malloy-publisher/malloy-package@latest <name> -- --data <path/to/their-file.csv> (CSV, Parquet, or Excel .xlsx), keeping the --, which is how npm create passes options through. That path is relative to wherever you run the command, so if you scaffolded into a new directory it has to reach back out to their file; the scaffolder copies it into the package and leaves the original alone. A seeded package starts smaller than the sample one, since the scaffolder does not read their columns: expect a row count and an overview, and build the model from there. A package is just Malloy, so it can instead query a database connection the config defines. Because it writes a .mcp.json that did not exist when the client connected, the user has to restart or reconnect once before these tools appear, and their client will ask them to approve the new project-scoped server the first time. That only works when the workspace is at the session's own root, so if you scaffolded into a new directory below that root, the user has to open a session there instead: a .mcp.json further down is never discovered.

If you started the server yourself in this session, the tools still will not appear: your tool list was fixed when you connected, and you cannot reconnect yourself. Tell the user the tools are missing for that reason and ask them to run /mcp, select malloy, and choose Reconnect. The panel offers Authenticate first and reports Auth: not authenticated; that is a red herring, the endpoint has no auth. Restarting Claude Code also works. Continue once the tools are there.

When a user is present, do not route around it by calling the REST API with curl. It appears to work, so the user never learns their session is missing the tools, and you lose what they are for: grounded discovery instead of guessed names, malloy_compile instead of throwaway queries, and malloy_reloadPackage instead of a restart. Say the tools are missing and let the user fix it in five seconds. Running unattended, with nobody who can reconnect you, is different: there the REST API is the supported interface, not a workaround. Discovery, query, compile, and reload all have REST equivalents (malloy_searchDocs and malloy_getContext's plain-English ranking do not; read the bundled skills for syntax and ground from model metadata instead); the running server serves the full spec at http://localhost:4000/api-doc.yaml, and AGENTS.md carries the endpoint map.

1. Discover what exists (never guess names)

malloy_getContext is progressive. Call it with as much as you know: