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/markdown get the page’s Markdown from its regular URL, with Vary: Accept set 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 .md URLs work on every portal.
  • A better llms.txt: New title, description, and instructions options set the heading, summary, and agent guidance at the top of the file.
  • A canonical OpenAPI document: Set publish.path on an API (for example /openapi.json) to serve the processed schema at a stable URL. Add agentQuality: true to get build warnings for gaps that hurt LLM function calling, such as missing operationId values 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 MCP label in the sidebar instead of an HTTP method.
  • Custom endpoint URL: Set x-mcp-server.url when 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: true in an API’s options when 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.