Document x-mint.mcp extension for MCP tool control

api-playground/openapi-setup.mdx

@@ -4,7 +4,7 @@
 keywords: ["OpenAPI", "API specification", "Swagger"]
 ---
 
 OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.
 
 ## Add an OpenAPI specification file
 
@@ -60,7 +60,7 @@
 
 ### Specify the base URL for your API
 
 To enable the API playground, add a `servers` field to your OpenAPI specification with your API's base URL.
 
 ```json
 {
@@ -147,7 +147,7 @@
 }
 ```
 
 The `x-default` extension is supported on `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields.
 
 You can also use `x-default` on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition.
 
@@ -258,6 +258,65 @@
 }
 ```
 
+### MCP
+
+Control which API endpoints are exposed as tools on your [MCP server](/ai/model-context-protocol) by adding `x-mint: mcp` to any operation. By default, all endpoints in your OpenAPI specification are available as MCP tools. Use this extension to disable specific endpoints, or to customize the tool name and description that AI applications see.
+
+```json {6-10}
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "x-mint": {
+          "mcp": {
+            "enabled": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `mcp` object supports the following properties:
+
+<ResponseField name="enabled" type="boolean" default="true">
+  Whether to expose this endpoint as an MCP tool. Set to `false` to hide the endpoint from your MCP server.
+</ResponseField>
+
+<ResponseField name="name" type="string">
+  Override the tool name that AI applications see. If not set, Mintlify generates a name from the operation ID or the HTTP method and path.
+</ResponseField>
+
+<ResponseField name="description" type="string">
+  Override the tool description that AI applications see. If not set, Mintlify uses the operation's `summary` or `description`.
+</ResponseField>
+
+You can customize the tool name and description to help AI applications understand when and how to use the endpoint:
+
+```json {6-10}
+{
+  "paths": {
+    "/users/search": {
+      "post": {
+        "summary": "Search users by filters",
+        "x-mint": {
+          "mcp": {
+            "name": "search_users",
+            "description": "Search for users by name, email, or role. Returns paginated results."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+<Note>
+  The legacy `x-mcp` extension at the operation level is still supported but `x-mint: mcp` is preferred. If both are present, `x-mint: mcp` takes precedence.
+</Note>
+
 ## Auto-populate API pages
 
 Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
@@ -446,7 +505,7 @@
 
 The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`.
 
 #### Autogenerate endpoint pages
 
 To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).
 
@@ -496,9 +555,9 @@
 
 </CodeGroup>
 
 ## Webhooks
 
 Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.
 
 Add a `webhooks` field to your OpenAPI document alongside the `paths` field.