docs(publishing): match the MCP page to the shipped server

[mlennie]

Publisher consolidated its MCP surface onto a single endpoint in publisher#884, and this page was never updated to match. A reader who follows it today configures their agent to a port that is not listening, and calls four tools that return Tool not found.

I checked every claim against the published @malloy-publisher/[email protected] over MCP rather than reading the source, since that package is what the npx command at the top of this page actually installs.

What the page claimed, and what 0.0.227 does

The page	Reality
A second MCP server for agents on :4041, set by AGENT_MCP_PORT, with a config block pointing at http://localhost:4041/mcp	Nothing listens on :4041, and AGENT_MCP_PORT appears nowhere in the codebase. Everything is served from :4040
malloy_projectList, malloy_packageList, malloy_packageGet, malloy_modelGetText	All removed. tools/call returns MCP error -32602: Tool ... not found. They did not move to resources either: resources/list and resources/templates/list are both empty
projectName	environmentName
malloy_executeQuery takes projectName, packageName, modelPath, query	Requires environmentName, packageName, modelPath. query is optional, because queryName runs a named query or view instead
Download the bridge from packages/server/dxt/malloy_bridge.py	404. #884 deleted it

What changed

The :4041 section folds into MCP Tools, since there is only one endpoint now. That section documents the three tools the server actually serves: malloy_getContext, malloy_executeQuery, malloy_searchDocs.

Discovery now documents progressive malloy_getContext, which is what replaced the four removed tools. Every parameter is optional, so an agent can start with nothing and narrow down. Calling it with no arguments returns the environments and their packages:

{"results":[{"kind":"environment","name":"malloy-samples","packages":["ecommerce","faa","imdb"]}]}

The stdio bridge still works, so that section is fixed rather than dropped. The script now ships inside packages/server/malloy_mcp.dxt, a Desktop Extension bundle, and still targets http://localhost:4040/mcp. Hosts that install .dxt files can use it directly; everyone else can unpack it, and the documented unzip command is one I ran.

Two parameter contracts documented the way the server enforces them

Both fail in ways a reader would not predict, and I got both wrong on the first pass:

• malloy_executeQuery needs sourceName alongside queryName. Running a view with queryName alone fails with Reference to undefined object, because the server emits run: top_categories with nothing to resolve it against. The server's own constant says "Either 'query' or both 'sourceName' and 'queryName' must be provided". This matters more than it sounds: the samples carry 42 views against 1 top-level query, and this page's own "Define Common Views" section steers readers toward views, so the bare-queryName path I first documented would have worked for roughly 1 entity in 43.
• malloy_getContext ignores packageName unless environmentName is set, and returns the environment list rather than an error. It fails silently, which is the worst shape, so the tiers are documented as cumulative and the silent-ignore is stated outright.

One thing the page never said

The endpoint is unauthenticated, and Publisher binds 0.0.0.0 by default (server.ts:160), which the MCP listener uses (server.ts:1859). So the npx command at the top of this page exposes malloy_executeQuery, and therefore the databases your models connect to, on every interface rather than loopback. Publisher's own AGENTS.md and docs/ai-agents.md both carry that warning; this page did not, which made it the only current description of the MCP surface without it. The wording is lifted from docs/ai-agents.md rather than invented, and I confirmed --host 127.0.0.1 really does reach the MCP listener.

Worth a separate publisher issue: --help (server.ts:105) advertises --host ... (default: localhost) while the code defaults to 0.0.0.0. The --help text is wrong, and is plausibly how the localhost framing reached these docs in the first place.

What I deliberately did not add

malloy_compile and malloy_reloadPackage landed on publisher main in publisher#887, but 0.0.227 was cut before that merged, so they are not in any release yet. Documenting them here would tell readers about tools their server does not have, which is the same defect this PR is fixing. They belong in the update that follows the release carrying them.

Verification

npm run build-prod green ("All docs compiled in 10.235s"). I checked the rendered mcp_agents.html, not just the source: no 4041, projectName, removed tool names, or the dead bridge path survive; the three tool tables render as real HTML; and the malloy_mcp.dxt link renders as a working anchor.

A sweep of the rest of the site found no other page carrying the same claims.

Every claim above was checked against the running server, not inferred: the tool list and parameter contracts came from tools/list, the removals from tools/call and resources/list, and the two parameter fixes from actually running a view both ways. The unzip command and the bridge test command in this page are both ones I ran end to end against 0.0.227, and the bridge returned exactly the three tools documented here.

[mlennie]

Pushed a second commit that widens this slightly beyond what the description says, so flagging it rather than letting it pass as a rename.

Two tools added. The page documented three tools; the shipped server serves five. malloy_compile and malloy_reloadPackage were deliberately left out when this branch was written, because the then current release predated them. That stopped being true when 0.0.228 shipped, so merging as-is would have landed a page that was already incomplete. Parameters come from compile_tool.ts and reload_package_tool.ts, and the count is pinned by server.protocol.spec.ts.

One correction that is a scope expansion, and the reason I am commenting. The Quick Start warning said the unauthenticated endpoint meant anyone who can reach port 4040 could run malloy_executeQuery against your databases. That framed the exposure as read-only, which stopped being true once malloy_reloadPackage existed: it mutates shared server state, and for a package whose stored metadata carries an install location a reload re-fetches from that source over the canonical directory, overwriting on-disk edits.

Publisher's own docs/ai-agents.md was corrected for exactly this in the commit that shipped the tools, and its message says plainly that the old sentence "was no longer true". This page was the last surface still carrying it, so the wording here is aligned to that doc, including its framing that the same effects are already reachable through the equivalent REST endpoints, so it is a reason to gate the deployment rather than to avoid the tools.

That matters more than a normal docs nit because build_docs_index.ts builds the bundled search index from this repo's src/documentation, so this page is what malloy_searchDocs hands to agents.

Deliberately not written: a "compile before reload for safety" rule. A failed reload leaves your files alone and keeps serving the previously compiled model, so compiling first is a speed-up for diagnostics, not a safety measure. Saying otherwise would have described the pre-#890 world.

Build is green and I checked the rendered output rather than just the source.