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/server@0.0.227 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.