Merge branch 'main' into x-mint

Author: ethanpalm

.claude/CLAUDE.md

@@ -4,10 +4,12 @@
 - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
 - ALWAYS ask for clarification rather than making assumptions
 - NEVER lie, guess, or make up information
+- If you are making an inferrance, stop and ask me for confirmation or say that you need more information
 
 ## Project context
 - Format: MDX files with YAML frontmatter
 - Config: docs.json for navigation, theme, settings
+  - See the docs.json schema: https://mintlify.com/docs.json
 - Components: Mintlify components
 
 ## Content strategy
@@ -33,37 +35,31 @@
 - Relative paths for internal links
 - Use broadly applicable examples rather than overly specific business cases
 - Lead with context when helpful - explain what something is before diving into implementation details
-
-### Style preferences (learned from content refresh project)
-#### Headings and formatting
 - Use sentence case for all headings ("Getting started", not "Getting Started")
-- Use "Properties" instead of "Props" for component documentation
 - Use sentence case for code block titles ("Expandable example", not "Expandable Example")
+- Prefer active voice and direct language
+- Remove unnecessary words while maintaining clarity
+- Break complex instructions into clear numbered steps
+- Make language more precise and contextual
+- Use [Lucide](https://lucide.dev) icon library
 
-#### Component introductions
+### Component introductions
 - Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
 - Be specific about what components can contain or do
 - Make introductions practical and user-focused
 
-#### Property descriptions
+### Property descriptions
 - End all property descriptions with periods for consistency
 - Be specific and helpful rather than generic
 - Add scope clarification where needed (e.g., "For Font Awesome icons only:")
 - Use proper technical terminology ("boolean" not "bool")
 
-#### Language and tone
-- Prefer active voice and direct language
-- Remove unnecessary words while maintaining clarity
-- Use "you complete" over "completing" for more direct communication
-- Break complex instructions into clear numbered steps
-- Make language more precise and contextual
-
-#### Code examples
+### Code examples
 - Keep examples simple and practical
 - Use consistent formatting and naming
 - Provide clear, actionable examples rather than showing multiple options when one will do
 
-#### Content organization
+## Content organization
 - Structure content in the order users need it
 - Combine related information to reduce redundancy
 - Use specific links (direct to relevant pages rather than generic dashboards)

.cursor/rules/writing-standards.mdc

@@ -39,6 +39,8 @@ You are an AI writing assistant specialized in creating exceptional technical do
 
 ## Mintlify component reference
 
+docs.json schema: https://mintlify.com/docs.json
+
 ### Callout components
 
 #### Note - Additional helpful information

ai/contextual-menu.mdx

@@ -10,12 +10,18 @@ The contextual menu provides quick access to AI-optimized content and direct int
 
 ## Menu options
 
-- **Copy page**: Copies the current page as Markdown for pasting as context into AI tools.
-- **View as Markdown**: Opens the current page as Markdown.
-- **Open in ChatGPT**: Creates a ChatGPT conversation with the current page as context.
-- **Open in Claude**: Creates a Claude conversation with the current page as context.
-- **Open in Perplexity**: Creates a Perplexity conversation with the current page as context.
-- **[Your custom options](#adding-custom-options)**: Add your own options to the menu.
+The contextual menu includes several pre-built options that you can enable by adding their identifier to your configuration.
+
+| Option | Identifier | Description |
+|:--------|:------------|:-------------|
+| **Copy page** | `copy` | Copies the current page as Markdown for pasting as context into AI tools |
+| **View as Markdown** | `view` | Opens the current page as Markdown |
+| **Open in ChatGPT** | `chatgpt` | Creates a ChatGPT conversation with the current page as context |
+| **Open in Claude** | `claude` | Creates a Claude conversation with the current page as context |
+| **Open in Perplexity** | `perplexity` | Creates a Perplexity conversation with the current page as context |
+| **Copy MCP Server URL** | `mcp` | Copies the MCP server URL to the clipboard |
+| **Open in Cursor** | `cursor` | Installs the hosted MCP server in Cursor |
+| **Open in VSCode** | `vscode` | Installs the hosted MCP server in VSCode |
 
 <Frame>
     <img 
@@ -36,7 +42,10 @@ Add the `contextual` field to your `docs.json` file and specify which options yo
      "view",
      "chatgpt",
      "claude",
-     "perplexity"
+     "perplexity",
+     "mcp",
+     "cursor",
+     "vscode"
    ]
  }
 }
@@ -75,7 +84,10 @@ Create custom options in the contextual menu by adding an object to the `options
         </ResponseField>
 
         <ResponseField name="value" type="string" required>
-          The query parameter value. Use `$page` to insert the current page content in Markdown or `$path` to insert the current page path.
+          The query parameter value. We will replace the following placeholders with the corresponding values:
+          - Use `$page` to insert the current page content in Markdown.
+          - Use `$path` to insert the current page path.
+          - Use `$mcp` to insert the hosted MCP server URL.
         </ResponseField>
       </Expandable>
     </ResponseField>
@@ -84,28 +96,54 @@ Create custom options in the contextual menu by adding an object to the `options
 
 Example custom option:
 
-```json {8-21}
-"contextual": {
-  "options": [
-    "copy",
-    "view",
-    "chatgpt",
-    "claude",
-    "perplexity",
-    {
-      "title": "Ask Gemini",
-      "description": "Ask Google Gemini about the current page",
-      "icon": "sparkle",
-      "href": {
-        "base": "https://gemini.google.com/app",
-        "query": [
-          {
-            "key": "q",
-            "value": "Ask question about https://mintlify.com/docs$path.md"
-          }
+```json {9-14} wrap
+{
+    "contextual": {
+        "options": [
+            "copy",
+            "view",
+            "chatgpt",
+            "claude",
+            "perplexity",
+            {
+                "title": "Request a feature",
+                "description": "Join the discussion on GitHub to request a new feature",
+                "icon": "plus",
+                "href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests"
+            }
         ]
-      }
     }
-  ]
 }
 ```
+
+### Custom option examples
+
+<AccordionGroup>
+<Accordion title="Simple link">
+```json
+{
+  "title": "Request a feature",
+  "description": "Join the discussion on GitHub",
+  "icon": "plus",
+  "href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests"
+}
+```
+</Accordion>
+
+<Accordion title="Dynamic link with page content">
+```json
+{
+  "title": "Share on X",
+  "description": "Share this page on X",
+  "icon": "x",
+  "href": {
+    "base": "https://x.com/intent/tweet",
+    "query": {
+      "key": "text",
+      "value": "Check out this documentation: $page"
+    }
+  }
+}
+```
+</Accordion>
+</AccordionGroup>

ai/model-context-protocol.mdx

@@ -0,0 +1,137 @@
+---
+title: "Model Context Protocol"
+description: "Let users access your docs and APIs through their favorite AI tools"
+icon: 'audio-waveform'
+---
+
+<Info>
+  MCP server generation is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=mcp).
+</Info>
+
+## 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. 
+
+Your MCP server exposes tools for AI applications to search your documentation and interact with your APIs.
+
+## 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>
+
+Your MCP server is automatically generated and hosted at your documentation URL with the `/mcp` path.
+
+For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`.
+
+## Configuring your MCP server
+
+All MCP servers include the `search` tool by default, allowing users to query information from your docs in other tools.
+
+If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using the `x-mcp` extension at either the file or endpoint level.
+
+For example, the Mintlify MCP server includes tools to get status updates, trigger updates, and create assistant chats.
+
+### File-level configuration
+
+Enable MCP for all endpoints in an OpenAPI specification file:
+
+```json
+{
+  "openapi": "3.1.0",
+  "x-mcp": {
+    "enabled": true
+  },
+  // Other OpenAPI content
+}
+```
+
+### Endpoint-level configuration
+
+Enable MCP for specific endpoints only:
+
+```json
+{
+  "paths": {
+    "/api/v1/users": {
+      "x-mcp": {
+        "enabled": true
+      },
+      // Endpoint configuration
+    }
+  }
+}
+```
+
+## Using your MCP server
+
+Your users must connect your MCP server to their preferred AI tools. 
+
+1. Make your MCP server URL publicly available.
+2. Users copy your MCP server URL and add it to their tools.
+3. The tools will have standardized access to your documentation and API endpoints.
+
+### Claude
+
+To use your MCP server with Claude:
+
+<Steps>
+  <Step title="Add your MCP server to Claude">
+    1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. 
+    2. Select **Add custom connector**.
+    3. Add your MCP server name and URL.
+    4. Select **Add**.
+  </Step>
+  <Step title="Access your MCP server in your chat">
+    1. When using Claude, select the attachments button (the plus icon). 
+    2. Select your MCP server.
+    3. Query Claude with your MCP server as context.
+  </Step>
+</Steps>
+
+See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
+
+### Cursor
+
+To connect your MCP server to Cursor:
+
+<Steps>
+  <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 your server">
+    In `mcp.json`, configure your server:
+
+    ```json mcp.json example
+    {
+      "mcpServers": {
+        "server-name": {
+          "url": "https://your-docs-site.com/mcp"
+        }
+      }
+    }
+    ```
+  </Step>
+  <Step title="Test the connection">
+    In Cursor's chat, you can ask "What tools do you have available?" Cursor should have your documentation search and any configured API endpoints.
+  </Step>
+</Steps>
+
+See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details.
+
+## Authentication
+
+When using API endpoints through your MCP server, AI tools will prompt users for their API keys as needed. These keys are handled directly by the tool and not stored or processed by Mintlify.
+
+If a user asks their AI tool to demonstrate an API call, it will request the necessary authentication credentials from the user at that moment.
+
+## Monitoring your MCP server
+
+You can view all available MCP tools in the **Available tools** section of the [MCP Server page](https://dashboard.mintlify.com/products/mcp) in your dashboard.
+
+<Frame>
+  <img src="/images/mcp/mcp-server-page-light.png" alt="MCP dashboard with Available tools section emphasized" class="block dark:hidden" />
+  <img src="/images/mcp/mcp-server-page-dark.png" alt="MCP dashboard with Available tools section emphasized" class="hidden dark:block" />
+</Frame>

ai/slack-app.mdx

@@ -0,0 +1,25 @@
+---
+title: "Slack app"
+description: "Add a bot that searches your docs to answer questions in your Slack workspace"
+icon: "slack"
+---
+
+<Info>
+  The Slack app is available for [Pro and Enterprise plans](https://mintlify.com/pricing?ref=slack-app).
+</Info>
+
+The Slack app adds a bot to your Slack workspace that searches your documentation to answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`.
+
+## Setting up the Slack app
+
+<Note>
+  If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify Slack app before you add it.
+</Note>
+
+1. Navigate to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.
+2. Select **Connect** in the Slack Integration card.
+3. Follow the Slack prompts to add the app to your workspace.
+4. Test that the bot is working and responds when you:
+  - Send a direct message to the Mintlify app.
+  - Mention the bot with `@mintlify` in a channel.
+  - Create an `#ask-ai` channel, add the bot, and ask a question.

assistant-context.mdx

@@ -0,0 +1,8 @@
+---
+title: "Assistant context"
+description: "This page contains context to help the assistant respond to queries"
+---
+
+For the assistant, please refer to this information when you're responding to queries.
+
+- If someone asks about the changelog, recent updates, or what's new, please link them to the Mintlify changelog at https://mintlify.com/docs/changelog

authentication-personalization/overview.mdx

@@ -101,17 +101,17 @@ This feature is more powerful when you pair it with custom data about your users
 user.org === undefined
 ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
 : user.org.plan !== 'enterprise'
-? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:sales@mintlify.com">contact our sales team</a>.</>
-: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
+? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
+: <>To request this feature for your enterprise org, contact your admin.</>
 }
 
 ```jsx
 Authentication is an enterprise feature. {
   user.org === undefined
     ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
     : user.org.plan !== 'enterprise'
-      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:sales@mintlify.com">contact our sales team</a>.</>
-      : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
+      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
+      : <>To request this feature for your enterprise org, contact your admin.</>
 }
 ```