---
title: "Developer Portal: Agent-Ready Documentation and MCP Catalog"
description: "The Developer Portal serves Markdown to AI agents, publishes your OpenAPI document at a stable URL, and renders MCP servers as a searchable catalog."
canonicalUrl: "https://zuplo.com/changelog/2026/08/28/dev-portal-agent-ready-docs-mcp-catalog"
pageType: "changelog"
date: "2026-08-28"
tags: "dev-portal"
---
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](https://zuplo.com/docs/dev-portal/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](https://zuplo.com/docs/dev-portal/zudoku/configuration/llms)
and
[API reference configuration](https://zuplo.com/docs/dev-portal/zudoku/configuration/api-reference)
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](https://zuplo.com/docs/dev-portal/zudoku/openapi-extensions/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](https://zuplo.com/docs/dev-portal/zudoku/openapi-extensions/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](https://zuplo.com/docs/dev-portal/updating). Then see
[Documenting MCP servers](https://zuplo.com/docs/dev-portal/documenting-mcp-servers)
to set up your MCP server pages.