Help center/ask ai: add doc MCP server

src/_data/sidebars/help.yml

@@ -55,8 +55,8 @@ resources:
             link: /documentation-experience/markdown-support/
           - label: Topics
             link: /documentation-experience/topics/
-          - label: Ask AI & Markdown rendering
-            link: /documentation-experience/ask-ai-markdown-rendering/
+          - label: Ask AI capabilities
+            link: /documentation-experience/ask-ai-capabilities/
       - type: category
         label: Customization options
         link: /customization-options/
@@ -73,6 +73,8 @@ resources:
             link: /customization-options/head-injection-analytics-tools-integration/
           - label: Embed mode
             link: /customization-options/embed-mode/
+          - label: Headless doc portal (API)
+            link: /customization-options/headless-doc-portal-api/
       - type: category
         label: Changes management
         link: /changes-management/

src/_help/customization-options/headless-doc-portal-api.md

@@ -0,0 +1,37 @@
+---
+title: Headless doc portal (API)
+---
+
+- TOC
+{:toc}
+
+The Portal API provides access to API documentation hosted on Bump.sh programmatically. The API returns structured content through a REST API call, with the same level of content as the visual API doc.
+
+> The Portal API currently works on public docs.
+{: .info}
+
+## When to use the Portal API
+
+The Portal API is useful when you want to build your own integration on top of Bump.sh documentation, without relying on the MCP protocol. Typical use cases include:
+
+- Integrating documentation content into your own developer portal or tooling
+- Building a custom search interface for your API documentation
+- Feeding structured doc content into AI pipelines or RAG systems
+- Automating documentation audits or content extraction
+
+> If you're looking to connect your AI assistant to an API doc portal hosted on Bump.sh, the [portal MCP server](/help/documentation-experience/ask-ai-capabilities/#mcp-server) is the way to go. It's built on top of the Portal API.
+{: .info}
+
+## Explore the documentation structure
+
+You can use the [`GET /list`](https://https://developers.bump.sh/doc/portal/operation/operation-get-list) endpoint to list all child pages under a given URL in the portal hierarchy. It returns each page's URL, title, type, and a short description. It's useful as a starting point to understand what a portal contains before fetching specific pages.
+
+## Search across documentation
+
+You can use the [`GET /search`](https://https://developers.bump.sh/doc/portal/operation/operation-get-search) endpoint to search across all documentation pages in a portal by keyword. Results include URL, title, type, and a text excerpt for each page. You can optionally filter by page URL or by page type (`operation`, `model`, `guide`, etc.).
+
+## Retrieve page content
+
+You can use the [`GET /fetch`](https://https://developers.bump.sh/doc/portal/operation/operation-get-fetch) endpoint to retrieve the full content of one or more pages by their URLs (up to 10 per request). Content is returned in Markdown format.
+
+A common flow is to call `GET /search` first to identify relevant pages, then `GET /fetch` to read their full content.

src/_help/documentation-experience/ask-ai-capabilities.md

@@ -0,0 +1,126 @@
+---
+title: Ask AI capabilities
+---
+
+- TOC
+{:toc}
+
+Enable LLMs and AI agents to access your doc portal using Bump.sh Ask AI capabilities. When enabled, your documentation are made accessible through an MCP server and served as Markdown pages, so AI assistants and agents can search, navigate, and read your doc portal.
+
+## Enable Ask AI
+
+Ask AI can be enabled or disabled from your documentation or hub settings, under the "Ask AI" section.
+
+![Ask AI settings, a toggle to make a doc portal available to AI tools](/docs/images/help/ask-ai-settings.png)
+
+Enabling these capabilities:
+- Exposes an MCP server for the API doc/hub, available by adding `/mcp` at the end of the URL.
+- Makes every page available as Markdown (by appending `.md` to any URL).
+- Generates a **[llms.txt](/help/publish-documentation/seo-geo/#llmstxt-for-llm-crawlers)** file at the root of your documentation.
+
+## Ask AI dropdown in the documentation
+
+Many API consumers now rely on AI tools to help them quickly discover API capabilities. The Ask AI dropdown menu offers documentation users a way to either add the doc MCP server, open the current page in Claude/ChatGPT, or access the Markdown version.
+
+![ask-ai-dropdown.png](/docs/images/help/ask-ai-dropdown.png)
+
+Available options:
+
+| Option | Description |
+|---|---|
+| **Add to Cursor** | Adds the doc/hub MCP server to Cursor in one click. |
+| **Add to VS Code** | Adds the doc/hub MCP server to VS Code in one click. |
+| **Add to other AI tools (MCP)** | Shows the MCP server URL and a ready-to-use `mcp.json` snippet. |
+| **Open in ChatGPT** | Opens the current page in ChatGPT with the right Markdown page pre-linked. |
+| **Open in Claude** | Opens the current page in ChatGPT with the right Markdown page pre-linked. |
+| **View as Markdown** | Opens the Markdown version of the current page. |
+| **Copy as Markdown** | Copies the Markdown content of the current page to the clipboard. |
+
+## MCP server
+
+> Docs MCP servers are currently only available for public docs/hubs.
+{: .info}
+
+When Ask AI is enabled, Bump.sh exposes an MCP server for your doc/hub. AI agents can use it to search, navigate, and read your API documentation programmatically, without having to scrape HTML pages or parse raw OpenAPI files. As search results are computed on our side, based on your documentation, it reduces the risk of AI hallucinations: the AI should just output information provided by the MCP server.
+
+The MCP server URL is shown in your doc/hub settings and accessible from the Ask AI dropdown.
+
+> Note that each MCP server URL is scoped to a specific doc or hub: it will only expose information about the doc/hub it was activated on, not your entire Bump.sh doc portal.
+{: .info}
+
+### Available tools
+
+The MCP server exposes three tools:
+
+| Tool | Description |
+|---|---|
+| **list_pages** | Lists all child pages under a given URL in the documentation hierarchy. Returns each page's URL, title, type, and description. Useful as a starting point to explore what documentation is available before fetching specific pages. |
+| **search** | Searches across all documentation pages by keyword. Supports filtering by type (operation, schema, topic, authentication, webhook, etc.). Returns up to 20 matching results with their URL, title, type, and a text excerpt. |
+| **get_pages** | Retrieves the full content of one or more pages by their URLs. Accepts up to 10 URLs per request. Use this when you already know which pages you need, for example from `search` or `list_pages` results. |
+
+A typical request from an API user to the LLM, like "How do I do that using this API" will trigger the **search** tool to get the right API/operation, and then a **get_pages** to get the actual content.
+
+## Markdown rendering
+
+Every page of your documentation is available as Markdown by appending `.md` to its URL. Markdown versions strip the surrounding UI, providing leaner context for AI tools and reducing token costs.
+
+To access the Markdown version of a documentation, add `.md` at the end of the URL (or `/source.md` if you have a custom domain, when the URL is the root of your documentation).
+
+[On a documentation root](https://developers.bump.sh/doc/workspace/source.md) *(example truncated for visibility purposes).*
+```markdown
+# Bump.sh Api
+
+## Description
+This is version `1.0` of this API documentation. Last update on Jun 16, 2025.
+This is the official Bump.sh API documentation. Obviously created with Bump.sh.
+
+The Bump.sh API is a REST API. It enables you to [...]
+
+
+## Servers
+- https://bump.sh/api/v1: https://bump.sh/api/v1 ()
+
+
+## Endpoints
+- [Branches](https://developers.bump.sh/doc/workspace/group/endpoint-branches.md)
+- [Diffs](https://developers.bump.sh/doc/workspace/group/endpoint-diffs.md)
+- [...]
+
+
+## Webhooks
+- [Documentation change](https://developers.bump.sh/doc/workspace/group/webhook-documentation-change.md)
+````
+
+[For a specific operation](https://developers.bump.sh/doc/workspace/operation/operation-post-versions.md) *(example truncated for visibility purposes).*
+```markdown
+# Create a new version
+
+**POST /versions**
+
+Deploy a new version for a given documentation, which will become the current version.
+
+
+## Servers
+- https://bump.sh/api/v1: https://bump.sh/api/v1 ()
+
+
+## Authentication methods
+- Authorization token
+- Basic token
+
+
+## Body parameters
+Content-type: application/json
+The version creation request object
+- **documentation** (string)
+  UUID or slug of the documentation.
+- [...]
+
+## Responses
+### 201: Documentation version successfully created
+
+#### Body Parameters: application/json (object)
+- **id** (string)
+  Unique id of your version.
+- [...]
+```

src/_help/documentation-experience/index.md

@@ -11,4 +11,6 @@ The [API Explorer](/help/documentation-experience/api-explorer/) allows you to t
 
 To help you enrich your API documentation, Bump.sh supports [Markdown](/help/documentation-experience/markdown-support/), offering better formatting and the ability to add your own images.
 
-We also offer [topics](/help/documentation-experience/topics/): an exclusive custom property that allows you to add extra information to your documentation.
+We also offer [topics](/help/documentation-experience/topics/): an exclusive custom property that allows you to add extra information to your documentation.
+
+Enable LLMs and AI agents to access your doc portal using Bump.sh [Ask AI features](/help/documentation-experience/ask-ai-capabilities/). When enabled, your documentation are made accessible through an MCP server and offered as Markdown pages, so AI assistants and agents can search, navigate, and read your doc portal.

src/_redirects

@@ -32,6 +32,7 @@ https://help.bump.sh/custom-domains /help/customization-options/custom-domains/
 /help/continuous-integration/ci/ /help/continuous-integration/
 /help/hubs/hub-settings/#default-settings--visual-customization /help/hubs/customize-ui/
 /help/account/billing/ /help/organizations/billing/
+/help/documentation-experience/ask-ai-markdown-rendering/ /help/documentation-experience/ask-ai-capabilities/
 
 # Cribbed for the OpenAPI Specification Tutorial
 /guides/openapi/advanced-ref-usage/ /openapi/v3.1/advanced/splitting-documents-with-ref/