diff --git a/ai/contextual-menu.mdx b/ai/contextual-menu.mdx index 46c4890a..f5146f7d 100644 --- a/ai/contextual-menu.mdx +++ b/ai/contextual-menu.mdx @@ -20,9 +20,9 @@ The contextual menu includes several pre-built options that you can enable by ad | **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 | +| **Copy MCP server URL** | `mcp` | Copies your MCP server URL to the clipboard | +| **Connect to Cursor** | `cursor` | Installs your hosted MCP server in Cursor | +| **Connect to VS Code** | `vscode` | Installs your hosted MCP server in VS Code | - MCP server generation is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=mcp). - +import { PreviewButton } from "/snippets/previewbutton.jsx" ## About MCP servers @@ -20,21 +19,39 @@ Your MCP server exposes tools for AI applications to search your documentation a MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation. -Your MCP server is automatically generated and hosted at your documentation URL with the `/mcp` path. +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`. -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). ## 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 `mcp` object within the `x-mint` extension at either the file or endpoint level. +If you have a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=mcp), you can expose endpoints from your OpenAPI specification as MCP tools. -For example, the Mintlify MCP server includes tools to get status updates, trigger updates, and create assistant chats. +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. + + + The MCP configuration for the endpoint. + + + + Whether to expose the endpoint as an MCP tool. Takes precedence over the file-level configuration. + + + The name of the MCP tool. + + + The description of the MCP tool. + + + ### 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 { @@ -44,24 +61,46 @@ Enable MCP for all endpoints in an OpenAPI specification file: "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, + "name": "get-users", + "description": "Get a list of users" + }, + // ... } - }, - // Endpoint configuration + } + }, + "/api/v1/delete": { + "delete": { + // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool + // ... + } } } } @@ -69,35 +108,166 @@ Enable MCP for specific endpoints only: ## Using your MCP server -Your users must connect your MCP server to their preferred AI tools. +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. +3. Users access your documentation and API endpoints through their tools. -### Claude +These are some of the ways you can help your users connect to your MCP server: -To use your MCP server with Claude: + + + Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page of your documentation. + | Option | Identifier | Description | + | :----- | :--------- | :---------- | + | **Copy MCP server URL** | `mcp` | Copies your MCP server URL to the user's clipboard. | + | **Connect to Cursor** | `cursor` | Installs your MCP server in Cursor. | + | **Connect to VS Code** | `vscode` | Installs your MCP server in VS Code. | + + - + + Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + + + Create a guide for your users that includes your MCP server URL and the steps to connect it 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**. + 5. When using Claude, select the attachments button (the plus icon). + 6. Select your MCP server. + + + +See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details. + + + + + Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + + + Create a guide for your users that includes your MCP server URL and the command to connect it to Claude Code. + + ```bash + claude mcp add --transport http + ``` + + + +See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details. + + + + + Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + + + Create a guide for your users that includes your MCP server URL and the steps to connect it to Cursor. + + 1. Use Command + Shift + P (Ctrl + Shift + P 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. + 4. In `mcp.json`, configure your server: + + ```json + { + "mcpServers": { + "": { + "url": "" + } + } + } + ``` + + + + See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details. + + + + + Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL. + + + Create a guide for your users that includes your MCP server URL and the steps to connect it to VS Code. + + 1. Create a `.vscode/mcp.json` file. + 2. In `mcp.json`, configure your server: + + ```json + { + "servers": { + "": { + "type": "http", + "url": "" + } + } + } + ``` + + + + See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. + + + +### 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. + + + + At the top of this page, select the contextual menu and choose **Connect to Cursor** or **Connect to VS Code** to connect the Mintlify MCP server to the IDE of your choice. + + + +To use the Mintlify MCP server with Claude: + + + + 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. + 2. Select **Add custom connector**. + 3. Add the Mintlify MCP server: + - Name: `Mintlify` + - URL: `https://mintlify.com/docs/mcp` + 4. Select **Add**. - - 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. + + 1. When using Claude, select the attachments button (the plus icon). + 2. Select the Mintlify MCP server. + 3. Ask Claude a question about Mintlify. 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 use the Mintlify MCP server with Claude Code, run the following command: + +```bash +claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp +``` + +Test the connection by running: + +```bash +claude mcp list +``` + +See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details. + + + +Install in Cursor -To connect your MCP server to Cursor: +To connect the Mintlify MCP server to Cursor, click the **Install in Cursor** button. Or to manually connect the MCP server, follow these steps: @@ -105,31 +275,52 @@ To connect your MCP server to Cursor: 2. Search for "Open MCP settings". 3. Select **Add custom MCP**. This will open the `mcp.json` file. - - In `mcp.json`, configure your server: + + In `mcp.json`, add: - ```json mcp.json example + ```json { "mcpServers": { - "server-name": { - "url": "https://your-docs-site.com/mcp" + "Mintlify": { + "url": "https://mintlify.com/docs/mcp" } } } ``` - In Cursor's chat, you can ask "What tools do you have available?" Cursor should have your documentation search and any configured API endpoints. + In Cursor's chat, ask "What tools do you have available?" Cursor should show the Mintlify MCP server as an available tool. See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. + + + +Install in VS Code + +To connect the Mintlify MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add: + +```json +{ + "servers": { + "Mintlify": { + "type": "http", + "url": "https://mintlify.com/docs/mcp" + } + } +} +``` + +See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 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. +When you enable an API endpoint for MCP, the server includes the authentication requirements defined in your OpenAPI `securitySchemes` and `securityRequirement`. Any 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. +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. ## Monitoring your MCP server @@ -139,3 +330,30 @@ You can view all available MCP tools in the **Available tools** section of the [ MCP dashboard with Available tools section emphasized + +## Troubleshooting + + + + 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. + + + 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. + + + If AI tools aren't using your API endpoints effectively: + + 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. + + diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 29b8cf6e..6fa7f343 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -189,9 +189,26 @@ When `x-mint: href` is present, the navigation entry will link directly to the s ### 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. + + + The MCP configuration for the endpoint. + + + + Whether to expose the endpoint as an MCP tool. Takes precedence over the file-level configuration. + + + The name of the MCP tool. + + + The description of the MCP tool. + + + -```json {6-10} + +```json Selective enablement {6-10, 21} wrap { "paths": { "/users": { @@ -200,18 +217,45 @@ Expose endpoints as MCP tools by using `x-mint: mcp`: "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" } } } } ``` + + +For more information, see [Model Context Protocol](/ai/model-context-protocol). ## Auto-populate API pages diff --git a/docs.json b/docs.json index b8b2ba87..400643a8 100644 --- a/docs.json +++ b/docs.json @@ -357,7 +357,8 @@ "copy", "chatgpt", "claude", - "cursor" + "cursor", + "vscode" ] }, "redirects": [ diff --git a/installation.mdx b/installation.mdx index 62b591a7..82369043 100644 --- a/installation.mdx +++ b/installation.mdx @@ -130,7 +130,7 @@ mint rename While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files. -If you use Cursor, Windsurf, or VSCode, we recommend the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. +If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.