From 6a7fab9241138ee8a82ba9ec3fd59c07b14c45d5 Mon Sep 17 00:00:00 2001 From: Monty Lennie Date: Fri, 19 Jun 2026 16:54:18 -0600 Subject: [PATCH] docs(publishing): document the agent MCP server (retrieval tools and skills) Expand the MCP for AI Agents guide with a section covering the agent MCP server on :4041, the malloy_getContext and malloy_searchDocs retrieval tools, the two-phase get_context pattern, and the agent skills delivered as MCP prompts. Signed-off-by: Monty Lennie --- .../publishing/mcp_agents.malloynb | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/documentation/user_guides/publishing/mcp_agents.malloynb b/src/documentation/user_guides/publishing/mcp_agents.malloynb index 5bd4037f..89461120 100644 --- a/src/documentation/user_guides/publishing/mcp_agents.malloynb +++ b/src/documentation/user_guides/publishing/mcp_agents.malloynb @@ -107,6 +107,33 @@ Publisher exposes these tools to AI agents: --- +## Agent Retrieval Tools and Skills + +Alongside the core MCP server on `:4040`, Publisher runs a second MCP server for agents on `:4041` (set by `AGENT_MCP_PORT`). It serves two read-only retrieval tools plus the bundled agent skills, configured the same way as the core server but on the agent endpoint: + +```json +{ + "mcpServers": { + "malloy-publisher-agent": { + "url": "http://localhost:4041/mcp" + } + } +} +``` + +### Retrieval tools + +| Tool | Parameters | Description | +|------|------------|-------------| +| `malloy_getContext` | `environmentName`, `packageName`, `query`, `sourceName` (optional), `limit` (optional) | Given a plain-English question, returns the model entities (sources, views, named queries, and dimension/measure fields) most relevant to it, each with its model path and `#(doc)` description. | +| `malloy_searchDocs` | `query`, `limit` (optional) | Keyword search over a bundled index of the Malloy documentation, returning matching pages with a short excerpt and a link. | + +Use `malloy_getContext` in two phases: call it once with just a `query` to discover the most relevant sources and views, then optionally call it again with `sourceName` set to focus on the fields within one source. The `environmentName`, `packageName`, and `modelPath` it returns map directly onto `malloy_executeQuery`, so an agent can go from a question to a grounded query without guessing field names. + +### Skills as MCP prompts + +Publisher also ships a set of agent **skills**: short guides that teach an agent how to write Malloy, choose charts, and verify results. Skill-aware hosts (such as Claude Code and Claude Desktop) load the skill files directly. For hosts that only ingest MCP, the agent server also exposes each skill as an MCP prompt, so the same guidance is available either way: list them with `prompts/list` on the agent endpoint and fetch one with `prompts/get`. + ## Example Prompts Once connected, try these prompts: