MCP tool updates

ai/model-context-protocol.mdx

@@ -28,40 +28,60 @@
 
 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 `mcp` object within the `x-mint` extension at either the file or endpoint level.
+If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using 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.
 
-For example, the Mintlify MCP server includes tools to get status updates, trigger updates, and create assistant chats.
+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.
 
 ### File-level configuration
 
-Enable MCP for all endpoints in an OpenAPI specification file:
+Enable MCP for all endpoints by default in an OpenAPI specification file and selectively exclude endpoints:
 
 ```json
 {
   "openapi": "3.1.0",
   "x-mint": {
     "mcp": {
       "enabled": true
     }
   },
-  // Other OpenAPI content
+  // ...
+  "paths": {
+    "/api/v1/users": {
+      "get": {
+        "x-mint": {
+          "mcp": {
+            "enabled": false // Disables MCP for this endpoint
+          }
+        },
+        // ...
+      }
+    }
+  }
 }
 ```
 
 ### Endpoint-level configuration
 
-Enable MCP for specific endpoints only:
+Enable MCP for specific endpoints:
 
 ```json
 {
   "paths": {
     "/api/v1/users": {
-      "x-mint": {
-        "mcp": {
-          "enabled": true
+      "get": {
+        "x-mint": {
+          "mcp": {
+            "enabled": true
+          },
+          // ...
         }
-      },
-      // Endpoint configuration
+      }
+    },
+    "/api/v1/delete": {
+      "delete": {
+        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
+        // ...
+      }
     }
   }
 }
@@ -101,7 +121,7 @@
 
 <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>
@@ -127,9 +147,36 @@
 
 ## 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.
+When you enable an API endpoint for MCP, the server includes the authentication requirements defined in your OpenAPI `securitySchemes`. Any keys are handled directly by the tool and not stored or processed by Mintlify.
+
+If a user asks their AI tool to call a protected endpoint, the tool will request the necessary authentication credentials from the user at that moment.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="MCP server only shows search tool">
+    If your MCP server only exposes the search tool despite having an OpenAPI specification:
+
+    1. Verify your OpenAPI specification is valid and accessible.
+    2. Ensure you've explicitly enabled MCP for specific endpoints using `x-mint.mcp.enabled: true`.
+    3. Check your deployment logs for OpenAPI processing errors.
+
+    If OpenAPI processing fails, the server continues with just the search tool to maintain functionality.
+  </Accordion>
+  <Accordion title="Authentication issues">
+    If users report authentication problems:
+
+    1. Check that your OpenAPI specification includes proper `securitySchemes` definitions.
+    2. Confirm that enabled endpoints work with the specified authentication methods.
+  </Accordion>
+  <Accordion title="Tool descriptions missing or unclear">
+    If AI tools aren't using your API endpoints effectively:
 
-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.
+    1. Add detailed `summary` and `description` fields to your endpoints.
+    2. Ensure parameter names and descriptions are self-explanatory.
+    3. Use the MCP dashboard to verify how your endpoints appear as tools.
+  </Accordion>
+</AccordionGroup>
 
 ## Monitoring your MCP server
 

api-playground/openapi-setup.mdx

@@ -31,7 +31,7 @@
 
 ### Specifying the URL for your API
 
 To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.
 
 ```json
 {
@@ -189,29 +189,57 @@
 
 ### MCP
 
-Expose endpoints as MCP tools by using `x-mint: mcp`:
+Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-mint: mcp`. Only enable endpoints that are safe for public access through AI tools.
 
-```json {6-10}
+<CodeGroup>
+```json Selective enablement {6-10, 21} wrap
 {
   "paths": {
     "/users": {
       "post": {
         "summary": "Create user",
         "x-mint": {
           "mcp": {
             "enabled": true
+          },
+          // ...
+        }
+      }
+    },
+    "/users": {
+      "delete": {
+        "summary": "Delete user (admin only)",
+        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
+        // ...
+      }
+    }
+  }
+}
+```
+
+```json Global enablement {3-5, 9-12} wrap
+{
+  "openapi": "3.1.0",
+  "x-mcp": {
+      "enabled": true // All endpoints are exposed as MCP tools by default
+    },
+  "paths": {
+    "/api/admin/delete": {
+      "delete": {
+        "x-mint": {
+          "mcp": {
+            "enabled": false // Disable MCP for this endpoint
           }
         },
-        "parameters": [
-          {
-            // Parameter configuration
-          }
-        ]
+        "summary": "Delete resources"
       }
     }
   }
 }
 ```
+</CodeGroup>
+
+For more information, see [Model Context Protocol](/ai/model-context-protocol).
 
 ## Auto-populate API pages
 
@@ -416,10 +444,10 @@
 
 ### Autogenerate `MDX` files
 
 Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.
 
 <Note>
   Your OpenAPI document must be valid or the files will not autogenerate.
 </Note>
 
 The scraper generates:
@@ -431,12 +459,12 @@
 <Steps>
   <Step title="Generate `MDX` files.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
     ```
   </Step>
   <Step title="Specify an output folder.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
     ```
 
     Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.