mintlify · ethanpalm · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025
diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx
@@ -8,21 +8,31 @@
 
 ## About MCP servers
 
-The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates an MCP server from your documentation and OpenAPI specifications, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, Goose, and others) can connect to your documentation and APIs. 
+The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates an MCP server from your documentation and OpenAPI specifications, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, Goose, and others) can connect to your documentation and APIs.
 
 Your MCP server exposes tools for AI applications to search your documentation and interact with your APIs.
 
+### How MCP servers work
+
+When an MCP server is connected to an AI tool, the LLM can decide to use your documentation and API tools during response generation.
+
+- The LLM can proactively search your documentation or call your API endpoints while generating a response, not just when explicitly asked.
+- The LLM determines when to use tools based on the context of the conversation and the relevance of your documentation and APIs.
+- Each tool call happens during the generation process, allowing the LLM to incorporate real-time information from your documentation and APIs into its response.
+
+For example, if a user asks a coding question and the LLM determines that your API documentation is relevant, it can search your API documentation and include that information in the response without the user explicitly asking about your documentation.
+
 ## Accessing your MCP server
 
 <Note>
  MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation.
 </Note>

 Mintlify automatically generates an MCP server for your documentation and hosts it at your documentation URL with the `/mcp` path. For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`.

 You can see and copy your MCP server URL in your [dashboard](https://dashboard.mintlify.com/products/mcp).

 The `/mcp` path is reserved for hosted MCP servers and cannot be used for other navigation elements.

 ## Configuring your MCP server

@@ -32,7 +42,7 @@

 To expose endpoints as MCP tools, use the `mcp` object within the `x-mint` extension at either the file or endpoint level. For example, the Mintlify MCP server includes tools to create assistant chats, get status updates, and trigger updates.

 MCP servers follow a security-first approach where API endpoints are not exposed by default. You must explicitly enable endpoints to make them available as MCP tools. Only expose endpoints that are safe for public access through AI tools.

 <ResponseField name="mcp" type="object">
  The MCP configuration for the endpoint.
@@ -62,7 +72,7 @@
      "enabled": true
    }
  },
  // ...
  "paths": {
    "/api/v1/users": {
      "get": {
@@ -71,7 +81,7 @@
            "enabled": false // Disables MCP for this endpoint
          }
        },
        // ...
      }
    }
  }
@@ -219,7 +229,7 @@

 ### Example: Connecting to the Mintlify MCP server

 Connect to the Mintlify MCP server to interact with the Mintlify API and search our documentation. This will give you more accurate answers about how to use Mintlify in your local environment and demonstrates how you can help your users connect to your MCP server.

 <Tabs>
 <Tab title="Contextual menu">
@@ -239,7 +249,7 @@
    4. Select **Add**.
  </Step>
  <Step title="Access the MCP server in your chat">
    1. When using Claude, select the attachments button (the plus icon).
    2. Select the Mintlify MCP server.
    3. Ask Claude a question about Mintlify.
  </Step>
@@ -274,7 +284,7 @@
  <Step title="Open MCP settings">
    1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
    2. Search for "Open MCP settings".
    3. Select **Add custom MCP**. This will open the `mcp.json` file.
  </Step>
  <Step title="Configure the Mintlify MCP server">
    In `mcp.json`, add:

diff --git a/deploy/preview-deployments.mdx b/deploy/preview-deployments.mdx
@@ -8,13 +8,13 @@
  Preview deployments are available on [Pro and Custom plans](https://mintlify.com/pricing?ref=preview-deployments).
 </Info>

 Preview deployments let you see how changes to your docs will look before merging to production. Each preview creates a shareable URL that updates automatically as you push new changes. 

 Preview URLs are publicly viewable by default. Share a preview link with anyone who needs to review your changes.

 ## Create preview deployments

 Preview deployments are created automatically through pull requests or manually from your dashboard.

 ### Automatic previews

@@ -52,8 +52,21 @@
 By default, preview deployments are publicly accessible to anyone with the URL. You can restrict access to authenticated members of your Mintlify organization.

 1. Navigate to the **Previews** section in the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.
 2. Click the **Preview authentication** toggle to enable or disable preview authentication.
  <Frame>
     <img src="/images/previews/preview-auth-light.png" alt="The preview authentication toggle in the Add-ons page" className="block dark:hidden" />
     <img src="/images/previews/preview-auth-dark.png" alt="The preview authentication toggle in the Add-ons page" className="hidden dark:block" />
   </Frame>
+
+## Troubleshooting preview deployments
+
+If your preview deployment fails, try these troubleshooting steps.
+
+- **View the build logs**: In your [dashboard](https://dashboard.mintlify.com/), go to **Previews** and click the failed preview. The deployment logs show errors that caused failures.
+- **Check your configuration**:
+   - Invalid `docs.json` syntax
+   - Missing or incorrect file paths referenced in your navigation
+   - Invalid frontmatter in MDX files
+   - Broken image links or missing image files
+- **Validate locally**: Run `mint dev` locally to catch build errors before pushing to the repository.
+- **Check recent changes**: Review the most recent commits in your branch to identify what changes caused the build to fail.
diff --git a/editor.mdx b/editor.mdx
@@ -110,15 +110,7 @@
 
 Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor.
 
-Press <kbd>Command</kbd>
-
- + <kbd>P</kbd>
-
- on macOS or <kbd>Ctrl</kbd>
-
- + <kbd>P</kbd>
-
- on Windows to search for files by name.
+Press <kbd>Command</kbd> + <kbd>P</kbd> on macOS or <kbd>Ctrl</kbd> + <kbd>P</kbd> on Windows to search for files by name.
 
 ### Create new pages
 
@@ -279,7 +271,7 @@
  />
 </Frame>

 If you authorize Mintlify to your GitHub user, your commits will be signed as if you had made them yourself. If not, they will be signed by the Mintlify GitHub app.

 ### Pull requests and reviewing changes

@@ -306,7 +298,7 @@
    - Any specific areas that need review
  </Step>
  <Step title="Create and share">
    Select **Publish Pull Request**. The editor will provide a link to view your pull request.

    <Frame>
      <img

diff --git a/integrations/analytics/mixpanel.mdx b/integrations/analytics/mixpanel.mdx
@@ -9,7 +9,21 @@ Add the following to your `docs.json` file to send analytics to Mixpanel.
 ```json Analytics options in docs.json
 "integrations": {
     "mixpanel": {
-        "projectToken": "required"
+        "projectToken": "YOUR_MIXPANEL_PROJECT_TOKEN"
     }
 }
 ```
+
+Replace `YOUR_MIXPANEL_PROJECT_TOKEN` with your Mixpanel project token. You can find this in your [Mixpanel project settings](https://mixpanel.com/settings/project).
+
+## Tracked events
+
+Mintlify automatically tracks the following user interactions:
+
+- Page views
+- Search queries
+- Feedback submissions
+- Context menu interactions
+- Navigation clicks
+
+If you're not seeing events in Mixpanel, ensure your project token is correct and that no content security policies are blocking the Mixpanel script.
diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx
@@ -38,11 +38,4 @@ horizontal
 
 ## Enabling support integrations
 
-Integrate customer support widgets into your documentation. Add the `integrations` field to your `docs.json` file with your respective app ID.
-
-```json
-  "integrations": {
-    "intercom": "APP_ID",
-    "frontchat": "CHAT_ID"
-  }
-```
+Integrate customer support widgets into your documentation. Add the `integrations` field to your `docs.json` file with your respective app ID or chat ID. See each integration's documentation for instructions on finding your ID.
diff --git a/optimize/seo.mdx b/optimize/seo.mdx
@@ -1,10 +1,10 @@
 ---
 title: "SEO"
 description: "Optimize SEO with meta tag configuration for better search visibility."
 keywords: ["meta tags", "sitemap", "robots.txt", "SEO", "search engine optimization"]
 ---

 Mintlify automatically handles many SEO best practices, including:

 - Meta tag generation
 - Sitemap and `robots.txt` file generation
@@ -25,9 +25,9 @@
 }
 ```

 ### Set a canonical URL

 If you're using a custom domain, set the `canonical` meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

 ```json
 "seo": {
@@ -41,25 +41,49 @@
 
 To set page-specific meta tags, add them to a page's frontmatter.
 
+The following meta tags are supported at the page level:
+- `title` - Page title
+- `description` - Page description appears below the title on the page and in some search engine results
+- `keywords` - Comma-separated keywords
+- `og:title` - Open Graph title for social sharing
+- `og:description` - Open Graph description
+- `og:image` - Open Graph image URL
+- `og:url` - Open Graph URL
+- `og:type` - Open Graph type like "article" or "website"
+- `og:image:width` - Open Graph image width
+- `og:image:height` - Open Graph image height
+- `twitter:title` - Twitter card title
+- `twitter:description` - Twitter card description
+- `twitter:image` - Twitter card image
+- `twitter:card` - Twitter card type like "summary" or "summary_large_image"
+- `twitter:site` - Twitter site handle
+- `twitter:image:width` - Twitter image width
+- `twitter:image:height` - Twitter image height
+- `noindex` - Set to `true` to prevent search engine indexing
+- `robots` - Robots meta tag value
+
 ```mdx
 ---
 title: "Your example page title"
+description: "Page-specific description"
 "og:image": "link to your meta tag image"
+"og:title": "Social media title"
+keywords: ["keyword1", "keyword2"]
 ---
 ```
 
 <Note>
-  Meta tags with colons must be wrapped in quotes.
+  Meta tags with colons must be wrapped in quotes. The `keywords` field must be formatted as a YAML array.
 </Note>
 
 ## Common meta tags reference
 Below is a comprehensive list of meta tags you can add to your `docs.json`. These meta tags help improve your site's SEO, social sharing, and browser compatibility.

 <Note>
  The `og:image` adds a background image that Mintlify automatically overlays with your logo, page title, and description when generating social media previews.
 </Note>

 You can preview how your meta tags will appear on different platforms using [metatags.io](https://metatags.io/).

 ```json expandable
 "seo": {
@@ -169,11 +193,11 @@

 ### Custom sitemaps and robots.txt files

 To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `robots.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.

 ## Disabling indexing

 If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/organize/pages) of your page:

 ```
 ---
@@ -191,18 +215,18 @@
  }
 ```

 ## SEO best practices

 <AccordionGroup>
 <Accordion title="Write descriptive titles and descriptions">
 - Use clear, descriptive page titles (50-60 characters)
 - Write compelling descriptions (150-160 characters) 
 - Include relevant keywords
 - Make each page title and description unique
 </Accordion>

 <Accordion title="Optimize your content structure">
 - Use proper heading hierarchy (H1 → H2 → H3)
 - Write for humans first, search engines second
 - Include relevant keywords in headings and content
 - Keep URLs short, descriptive, and organized hierarchically
@@ -218,7 +242,7 @@

 <Accordion title="Image SEO">
 - Use descriptive file names for images
 - Always include alt text for accessibility and SEO
 - Optimize image file sizes for faster loading
 - Use relevant images that support your content
 </Accordion>

diff --git a/organize/navigation.mdx b/organize/navigation.mdx
@@ -94,7 +94,12 @@
 
 ### Default expanded state
 
-Set `expanded: true` on a group to make it expanded by default in the navigation sidebar. This is useful for highlighting important sections or improving discoverability of key content.
+Use the `expanded` property to control the default state of a group in the navigation sidebar.
+
+- `expanded: true`: Group is expanded by default.
+- `expanded: false` or omitted: Group is collapsed by default.
+
+This is useful for highlighting important sections or improving discoverability of key content.
 
 ```json
 {
@@ -249,9 +254,9 @@
 }
 ```

 For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path. 

 Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal.

 ```json
 {
@@ -277,7 +282,7 @@

 ## Dropdowns

 Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.

 <img
  className="block dark:hidden pointer-events-none"
@@ -392,7 +397,7 @@

 Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.

 Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.

 ```json
 {
@@ -486,7 +491,7 @@

 In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.

 We currently support the following languages for localization:

 <CardGroup cols={2}>
  <Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
@@ -540,7 +545,7 @@

 ## Nesting

 You can use any combination of anchors, tabs, dropdowns, and products. The components can be nested within each other interchangeably to create your desired navigation structure.

 <CodeGroup>

@@ -662,7 +667,7 @@

 ## Breadcrumbs

 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the `styling` property in your `docs.json`.

 <CodeGroup>

@@ -686,10 +691,10 @@

 ### Enable auto-navigation for groups

 When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.

 - Set to `true` to force automatic navigation to the first page when a navigation group is selected.
 - Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
 - Leave unset to use the theme's default behavior.

 <CodeGroup>