Skip to content

Update MCP docs #968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 29, 2025
+83 −65
Merged

Update MCP docs #968

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
17da392
update MCP page
ethanpalm Jul 29, 2025
0e4158e
add Claude steps
ethanpalm Jul 29, 2025
98e5731
add cursor steps
ethanpalm Jul 29, 2025
1a2d1af
use Steps
ethanpalm Jul 29, 2025
ccb0410
move configuration section
ethanpalm Jul 29, 2025
4d2136f
remove resources
ethanpalm Jul 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 83 additions & 65 deletions ai/model-context-protocol.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,70 +1,40 @@
---
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
<Info>
MCP server generation is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=mcp).
</Info>

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

<Note>
MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation.
</Note>

## Generating your MCP server

Public documentation hosted on Mintlify can be extracted as an MCP server using the following command:

```bash
npx mint-mcp add <your-subdomain-or-domain>
```

Examples:

```bash
# Using subdomain
npx mint-mcp add mintlify
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.

# Using domain
npx mint-mcp add mintlify.com
```

### Authentication

When you run the command, you'll need to provide two API keys, `External Admin Key` and `Assistant API Key`.
Your MCP server exposes tools for AI applications to search your documentation and interact with your APIs.

These can be found in your [dashboard](https://dashboard.mintlify.com/settings/organization/api-keys) under **Settings > API Keys**.
## Accessing your MCP server

<Frame>
<img src="/images/mcp/mcp-terminal.png" alt="Terminal prompt asking What is the Bearer Token for Mintlify External API?" />
</Frame>

### Select MCP clients

After authentication, you'll choose which MCP clients to enable for your server:
<Note>
MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation.
</Note>

<Frame>
<img src="/images/mcp/mcp-terminal-completed.png" alt="MCP Clients listed in the terminal." />
</Frame>
Your MCP server is automatically generated and hosted at your documentation URL with the `/mcp` path.

Once configured, your MCP server is ready to use with the command provided in the terminal.
For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`.

## 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.

### Adding API functions
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.

#### File-level configuration
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
{
Expand All @@ -76,7 +46,7 @@
}
```

#### Endpoint-level configuration
### Endpoint-level configuration

Enable MCP for specific endpoints only:

Expand All @@ -93,27 +63,75 @@
}
```

### Authentication handling
## 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.

Check warning on line 100 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L100 

Did you really mean 'Ctrl'?
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.

If your OpenAPI spec defines authentication using `securitySchemes`, these authentication methods will be automatically applied to your MCP server.
## Authentication

### Monitoring your MCP server
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.

After publishing your changes, you can view all available MCP tools in the **Available Tools** section on the MCP server page in your dashboard.
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>

## Distribution

### User installation

Your users can install and use your MCP server with:

```bash
npx mint-mcp add <your-subdomain-or-domain>
```

This provides them with a ready-to-use MCP server that connects your documented functions to AI applications.