Document that download-spec publishes /.well-known/api-catalog

ai/llmstxt.mdx

@@ -26,7 +26,7 @@
 
 Mintlify adds HTTP headers to every response, including [Markdown responses](/ai/markdown-export) and 404 pages, so AI tools can discover your `llms.txt` files and other agent resources without prior knowledge of their location:
 
-- `Link`: Follows the standard HTTP `Link` header format for resource discovery. Advertises `llms.txt`, `llms-full.txt`, your API catalog, [MCP server card](/ai/model-context-protocol#discovery-endpoint), [agent card](/ai/skillmd#agent-card), and [agent skills index](/ai/skillmd#skills-discovery-endpoints).
+- `Link`: Follows the standard HTTP `Link` header format for resource discovery. Advertises `llms.txt`, `llms-full.txt`, your [API catalog](/api-playground/openapi-setup#let-visitors-download-your-spec) (served only when you enable `download-spec`), [MCP server card](/ai/model-context-protocol#discovery-endpoint), [agent card](/ai/skillmd#agent-card), and [agent skills index](/ai/skillmd#skills-discovery-endpoints).
 - `X-Llms-Txt`: A convenience header for tools that check for `llms.txt` support.
 
 ```http Response headers
@@ -69,14 +69,14 @@
 - [API reference (250 pages)](https://docs.example.com/_llms/api-reference.md): Endpoint documentation for the example API
 ```
 
 A generated index can link to further indexes. For example, `/_llms/api-reference.md` can link to `/_llms/api-reference/admin.md` when a group is too large for a single file. Agents should follow these index links recursively until they reach documentation page links. Mintlify may shorten page descriptions in a split index to keep each file under the character limit.
 
 The generated files are part of `llms.txt` and do not need to exist in your repository. They are separate from `llms-full.txt`.
 
 The `/_llms/` route uses the same base path as your documentation:
 
 - A root-hosted site serves an index at `https://docs.example.com/_llms/api-reference.md`.
 - A site hosted at `/docs` serves it at `https://example.com/docs/_llms/api-reference.md`.
 
 If you use a reverse proxy or path allowlist, forward the generated route in addition to `llms.txt`. A broad `<base-path>/*` rule already includes `<base-path>/_llms/*`. With granular rules, add `<base-path>/_llms/*` explicitly. See [Reverse proxy](/deploy/reverse-proxy#routing-configuration) for routing guidance.
 

api-playground/openapi-setup.mdx

@@ -212,15 +212,15 @@
 
 ## Transform your spec with overlays
 
 Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify an OpenAPI specification without editing its source file. Overlays are separate JSON or YAML files that describe an ordered list of changes, which is useful when a specification is generated by another tool or maintained by another team. Common uses include renaming paths, replacing server URLs, and removing internal endpoints.
 
 Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, `openapi` frontmatter references, and `mint validate` all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.
 
 ### Create an overlay document
 
 An overlay document has an `overlay` version, an `info` object with a `title` and `version`, and an `actions` array. Each action selects nodes with a `target` [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression and applies one modifier:
 
 - `update`: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.
 - `remove`: Deletes each targeted node when set to `true`.
 - `copy`: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.
 
@@ -264,11 +264,11 @@
 
 ### Auto-discover overlays
 
 Any JSON or YAML file in your repository with a top-level `overlay` key is treated as an overlay document. If its `extends` field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an `extends` field never apply automatically.
 
 An explicit `overlays` list replaces auto-discovery for that specification. Set `"overlays": []` to disable all overlays for a specification, including auto-discovered ones.
 
 Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.
 
 ### Rename a path
 
@@ -306,8 +306,10 @@
 
 When enabled, clicking the option downloads your OpenAPI spec directly. Projects with multiple specs receive them bundled as `api-specs.zip`. On projects behind `auth` or `userAuth`, only authenticated readers can download the spec.
 
+Enabling `download-spec` also publishes an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog`. The catalog links to each OpenAPI spec in your `docs.json` so AI agents can discover your API without crawling your docs. Without `download-spec`, `/.well-known/api-catalog` returns a 404. On projects behind `auth` or `userAuth`, only authenticated readers can access the catalog.
+
 <Warning>
   The downloaded OpenAPI spec is unfiltered and does not respect [authentication groups](/deploy/authentication-setup). Any authenticated reader who can open the contextual menu receives the full spec, including endpoints and schemas that would otherwise be hidden from their group. Do not enable `download-spec` on an authenticated site if your OpenAPI spec contains endpoints or fields you consider sensitive.
 </Warning>
 
 ## Customize your endpoint pages
@@ -420,7 +422,7 @@
 
 ### Collapse playground fields
 
 Collapse object-type fields in the API playground by default using `x-mint: playground` with `expand: false` on any operation. Request sections like Authorization, Headers, Query, Path, and Body always stay expanded, and so does the top-level body object. Object fields nested within them start collapsed, so readers expand only the fields they want to interact with. If `expand` is not set, object fields are expanded by default.
 
 ```json {6-10}
 {

help-center/register-external-mcp-server-in-discovery.mdx

@@ -6,7 +6,7 @@
 
 Mintlify hosts a search MCP server for every site and advertises it through the `/.well-known/mcp`, `/.well-known/mcp.json`, `/.well-known/mcp/server-card.json`, and `/.well-known/mcp/server-cards.json` endpoints described in [Search MCP server](/ai/model-context-protocol#discovery-endpoint). These endpoints are generated automatically and only list the MCP servers Mintlify hosts for your site (the public `/mcp` endpoint, and `/authed/mcp` if you use authentication). There is no `docs.json` field for adding a second, externally hosted MCP server to those responses.
 
-The same applies to the `/.well-known/api-catalog` endpoint that Mintlify advertises through the [agent `Link` header](/ai/llmstxt#link-header): that catalog lists OpenAPI documents ingested from your `docs.json`, not MCP servers.
+The same applies to the `/.well-known/api-catalog` endpoint that Mintlify advertises through the [agent `Link` header](/ai/llmstxt#link-header): that catalog lists OpenAPI documents ingested from your `docs.json`, not MCP servers. The catalog is only served when you [opt into spec downloads](/api-playground/openapi-setup#let-visitors-download-your-spec).
 
 If you run your own MCP server outside Mintlify and want it discoverable alongside the built-in one on your docs domain, use one of the options below.
 
@@ -65,11 +65,11 @@
 - Add a page to your docs that lists both MCP server URLs and how to connect each one in Claude, Cursor, VS Code, or another client.
 - Add [contextual menu](/ai/contextual-menu) entries for the built-in server so users can copy the URL or install commands in one click. The contextual menu options only cover the Mintlify-hosted MCP server, so document the external URL manually alongside them.
 
 Clients that support multiple MCP servers can be pointed at the built-in `/mcp` endpoint and the external URL independently; they do not need to be listed in a single discovery document to be usable.
 
 ## What Mintlify does not currently support
 
 - Adding an external MCP server URL to a `docs.json` field so Mintlify includes it in `/.well-known/mcp*` responses.
 - Listing MCP servers under `/.well-known/api-catalog`. That endpoint is scoped to OpenAPI documents.
 
 If either of these would unblock your setup, contact [support@mintlify.com](mailto:support@mintlify.com) with your use case.