From 17da392c5dff62b20654cfe86952cc16e583f587 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 18:24:22 -0700 Subject: [PATCH 1/6] update MCP page --- ai/model-context-protocol.mdx | 89 +++++++++++++++-------------------- 1 file changed, 37 insertions(+), 52 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 46ea0b04d..5fc61845b 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -1,70 +1,71 @@ --- title: "Model Context Protocol" -description: "Generate MCP servers from your documentation or OpenAPI specs" +description: "Let users access your docs and APIs through their favorite AI tools" icon: 'audio-waveform' --- -## Overview + + MCP server generation is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=mcp). + -The Model Context Protocol (MCP) is an open protocol that connects your functions to LLMs and AI applications. With Mintlify's integration, you can automatically generate an MCP server from your existing documentation or OpenAPI specifications, enabling seamless AI-powered interactions with your product. +## 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 three core components to AI applications: + +- **Tools**: Functions that can be called by the AI application, including documentation search and API calls. +- **Resources**: Your documentation content, API responses, and other data. +- **Prompts**: Pre-defined templates that help users interact with your documentation. + +This structure allows any MCP-compatible tool to understand and work with your documentation in a consistent way. + +## Accessing your MCP server MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation. -## Generating your MCP server - -Public documentation hosted on Mintlify can be extracted as an MCP server using the following command: +Your MCP server is automatically generated and hosted at your documentation URL with the `/mcp` path. -```bash -npx mint-mcp add -``` +For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`. -Examples: +## Using your MCP server -```bash -# Using subdomain -npx mint-mcp add mintlify +Your users must connect your MCP server to their preferred AI tools. -# Using domain -npx mint-mcp add mintlify.com -``` +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 with search, API endpoints, and prompts. -### Authentication +### Claude -When you run the command, you'll need to provide two API keys, `External Admin Key` and `Assistant API Key`. +TODO: -These can be found in your [dashboard](https://dashboard.mintlify.com/settings/organization/api-keys) under **Settings > API Keys**. +### Cursor - - Terminal prompt asking What is the Bearer Token for Mintlify External API? - +TODO: -### Select MCP clients -After authentication, you'll choose which MCP clients to enable for your server: +## Authentication - - MCP Clients listed in the terminal. - +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. -Once configured, your MCP server is ready to use with the command provided in the terminal. +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. ## Configuring your MCP server -Now let's take a look at how to configure your MCP server. - -### Default functionality - -All MCP servers include the `search` tool by default, allowing users to query information across your entire documentation. +All MCP servers include the `search` tool by default, allowing users to query information from your docs in other tools. ### Adding API functions 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 a specification file: +Enable MCP for all endpoints in an OpenAPI specification file: ```json { @@ -93,27 +94,11 @@ Enable MCP for specific endpoints only: } ``` -### Authentication handling +## Monitoring your MCP server -If your OpenAPI spec defines authentication using `securitySchemes`, these authentication methods will be automatically applied to your MCP server. - -### Monitoring your MCP server - -After publishing your changes, you can view all available MCP tools in the **Available Tools** section on the MCP server page in your dashboard. +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. MCP dashboard with Available tools section emphasized - -## Distribution - -### User installation - -Your users can install and use your MCP server with: - -```bash -npx mint-mcp add -``` - -This provides them with a ready-to-use MCP server that connects your documented functions to AI applications. From 0e4158efed6bee1a9606e3cb8e54ffaf97f8637a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 18:35:20 -0700 Subject: [PATCH 2/6] add Claude steps --- ai/model-context-protocol.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 5fc61845b..75e1777a6 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -12,11 +12,10 @@ icon: 'audio-waveform' 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 three core components to AI applications: +Your MCP server exposes tools and resources to AI applications: - **Tools**: Functions that can be called by the AI application, including documentation search and API calls. - **Resources**: Your documentation content, API responses, and other data. -- **Prompts**: Pre-defined templates that help users interact with your documentation. This structure allows any MCP-compatible tool to understand and work with your documentation in a consistent way. @@ -36,11 +35,18 @@ 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 with search, API endpoints, and prompts. +3. The tools will have standardized access to your documentation and API endpoints. ### Claude -TODO: +To use your 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 your MCP server URL and select **Add**. +4. When using Claude, select the attachments button and select your MCP server to add it as context for your chat. + +See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details about connecting Claude to a remote MCP server. ### Cursor From 98e57316cad802b1efe6b9c2a81cf0ce015f8979 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 18:44:28 -0700 Subject: [PATCH 3/6] add cursor steps --- ai/model-context-protocol.mdx | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 75e1777a6..9c1eac08f 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -46,12 +46,29 @@ To use your MCP server with Claude: 3. Add your MCP server URL and select **Add**. 4. When using Claude, select the attachments button and select your MCP server to add it as context for your chat. -See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details about connecting Claude to a remote 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. ### Cursor -TODO: +To connect your MCP server to Cursor: +1. Open Cursor settings: 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**. +4. In `mcp.json`, configure your server: + +```json mcp.json example +{ + "mcpServers": { + "server-name": { + "url": "https://your-docs-site.com/mcp" + } + } +} +``` +5. Test the connection: In Cursor's chat, you can ask "What tools do you have available?" to see your documentation search and any configured API endpoints + +See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. ## Authentication From 1a2d1aff25a82bdb05a164a2a8147abb524f50bb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 19:15:11 -0700 Subject: [PATCH 4/6] use Steps --- ai/model-context-protocol.mdx | 53 +++++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 9c1eac08f..5bd6a51e2 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -41,10 +41,19 @@ Your users must connect your MCP server to their preferred AI tools. To use your 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 your MCP server URL and select **Add**. -4. When using Claude, select the attachments button and select your MCP server to add it as context for your chat. + + + 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**. + + + 1. When using Claude, select the attachments button (the plus icon). + 2. Select your MCP server. + 3. The menu displays all resources available to your MCP server. Select the resources you want to use in your chat. + + See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details. @@ -52,21 +61,29 @@ See the [Model Context Protocol documentation](https://modelcontextprotocol.io/d To connect your MCP server to Cursor: -1. Open Cursor settings: 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**. -4. In `mcp.json`, configure your server: - -```json mcp.json example -{ - "mcpServers": { - "server-name": { - "url": "https://your-docs-site.com/mcp" + + + 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. + + + In `mcp.json`, configure your server: + + ```json mcp.json example + { + "mcpServers": { + "server-name": { + "url": "https://your-docs-site.com/mcp" + } + } } - } -} -``` -5. Test the connection: In Cursor's chat, you can ask "What tools do you have available?" to see your documentation search and any configured API endpoints + ``` + + + In Cursor's chat, you can ask "What tools do you have available?" Cursor should have your documentation search and any configured API endpoints. + + See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. From ccb04104d18639ce5879dfa3702472053871bb0e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 19:16:45 -0700 Subject: [PATCH 5/6] move configuration section --- ai/model-context-protocol.mdx | 80 +++++++++++++++++------------------ 1 file changed, 39 insertions(+), 41 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 5bd6a51e2..8c4771bd1 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -29,6 +29,45 @@ Your MCP server is automatically generated and hosted at your documentation URL 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. @@ -93,47 +132,6 @@ When using API endpoints through your MCP server, AI tools will prompt users for 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. -## Configuring your MCP server - -All MCP servers include the `search` tool by default, allowing users to query information from your docs in other tools. - -### Adding API functions - -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 - } - } -} -``` - ## 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. From 4d2136f5b34348bf6131a1f7cee983d131ca70e2 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 28 Jul 2025 20:38:00 -0700 Subject: [PATCH 6/6] remove resources --- ai/model-context-protocol.mdx | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 8c4771bd1..b8da90f1c 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -12,12 +12,7 @@ icon: 'audio-waveform' 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 and resources to AI applications: - -- **Tools**: Functions that can be called by the AI application, including documentation search and API calls. -- **Resources**: Your documentation content, API responses, and other data. - -This structure allows any MCP-compatible tool to understand and work with your documentation in a consistent way. +Your MCP server exposes tools for AI applications to search your documentation and interact with your APIs. ## Accessing your MCP server @@ -87,10 +82,10 @@ To use your MCP server with Claude: 3. Add your MCP server name and URL. 4. Select **Add**. - + 1. When using Claude, select the attachments button (the plus icon). 2. Select your MCP server. - 3. The menu displays all resources available to your MCP server. Select the resources you want to use in your chat. + 3. Query Claude with your MCP server as context.