Developer Portal: Agent-Ready Documentation and MCP Catalog
The Developer Portal now does more for the AI agents reading your docs and for
the developers connecting to your MCP servers. Agents can request Markdown
instead of HTML, find a canonical OpenAPI document, and get a better llms.txt.
MCP servers get their own catalog view, a dedicated sidebar badge, and more
control over the install instructions. These features ship in Zudoku 0.86.0 and
later.
Agent-ready documentation
Every documentation page already has a Markdown version at its .md URL. On top
of that:
- Markdown at the page URL: Requests that send
Accept: text/markdownget the page’s Markdown from its regular URL, withVary: Acceptset so caches keep HTML and Markdown apart. This is on by default when Markdown export is on, and works on portals with server-side rendering enabled. The.mdURLs work on every portal. - A better
llms.txt: Newtitle,description, andinstructionsoptions set the heading, summary, and agent guidance at the top of the file. - A canonical OpenAPI document: Set
publish.pathon an API (for example/openapi.json) to serve the processed schema at a stable URL. AddagentQuality: trueto get build warnings for gaps that hurt LLM function calling, such as missingoperationIdvalues or untyped request bodies.
See the llms.txt configuration and API reference configuration docs.
MCP server catalog
Add x-zudoku-type: mcp-catalog to the root of an OpenAPI document to render it
as a single searchable page of MCP server cards instead of a REST reference.
Tags become filter chips, and selecting a card opens the server’s install
instructions and its tool list. Filters and selections live in the URL, so you
can link to them. Routes that use Zuplo’s MCP Server handler or the MCP Gateway
are marked as MCP servers automatically. See
x-zudoku-type.
More control over MCP server pages
- MCP badge: MCP server operations show an
MCPlabel in the sidebar instead of an HTTP method. - Custom endpoint URL: Set
x-mcp-server.urlwhen a server runs on its own hostname. An absolute URL replaces the derived endpoint, and a path is appended to the selected server URL. See x-mcp-server. - Hide auth instructions: Set
disableMcpAuthInstructions: truein an API’soptionswhen clients get credentials another way. The install card then shows no auth header or API key steps.
Getting started
Update your project’s zudoku package with npm install zudoku@latest in the
docs directory, as described in
Updating the Dev Portal. Then see
Documenting MCP servers
to set up your MCP server pages.