Model Context Protocol

让用户通过他们常用的 AI 工具访问你的文档和 API

​

关于 MCP 服务器

Model Context Protocol（MCP）是一种开放协议，可在 AI 应用与外部服务（如文档）之间建立标准化连接。Mintlify 会基于你的文档和 OpenAPI 规范生成一个 MCP 服务器，使你的内容为更广泛的 AI 生态做好准备，任何 MCP 客户端（如 Claude、Cursor、Goose 等）都可以连接到你的文档和 API。

你的 MCP 服务器会向 AI 应用提供工具，用于搜索你的文档并与 API 交互。

​

访问你的 MCP 服务器

仅能为公开文档生成 MCP 服务器。需要终端用户认证的文档无法用于生成服务器。

Mintlify 会为你的文档自动生成一个 MCP 服务器，并将其托管在你的文档 URL 的 /mcp 路径下。例如，Mintlify 的 MCP 服务器位于 https://mintlify.com/docs/mcp。

你可以在控制台查看并复制你的 MCP 服务器 URL。

/mcp 路径保留用于托管 MCP 服务器，不能用于其他导航元素。

​

配置你的 MCP 服务器

所有 MCP 服务器默认包含 search 工具，允许用户在其他工具中查询你文档中的信息。

如果你使用的是 Pro 或 Enterprise 方案，可以将 OpenAPI 规范中的端点暴露为 MCP 工具。

要将端点暴露为 MCP 工具，请在文件级或端点级的 x-mint 扩展中使用 mcp 对象。例如，Mintlify 的 MCP 服务器包含用于创建 AI 助手会话、获取状态更新和触发更新的工具。

MCP 服务器遵循安全优先原则，API 端点默认不对外暴露。你必须显式启用端点，才能将其作为 MCP 工具使用。仅暴露可通过 AI 工具公开访问且安全的端点。

mcp · object

该端点的 MCP 配置。

显示 MCP

enabled · boolean

是否将该端点暴露为 MCP 工具。其优先级高于文件级配置。

name · string

MCP 工具名称。

description · string

MCP 工具说明。

​

文件级配置

在一个 OpenAPI 规范文件中，默认为所有端点启用 MCP，并可选择性地排除部分端点：

{
  "openapi": "3.1.0",
  "x-mint": {
    "mcp": {
      "enabled": true
    }
  },
  // ...
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": false // 禁用此端点的 MCP
          }
        },
        // ...
      }
    }
  }
}

​

端点级配置

为特定端点启用 Model Context Protocol（MCP）：

{
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "get-users",
            "description": "获取用户列表"
          },
          // ...
        }
      }
    },
    "/api/v1/delete": {
      "delete": {
        // 没有 `x-mint: mcp`，所以此端点不会作为 MCP 工具公开
        // ...
      }
    }
  }
}

​

使用你的 MCP 服务器

你的用户需要将你的 MCP 服务器连接到他们常用的 AI 工具。

1. 将你的 MCP 服务器 URL 公开可访问。
2. 让用户复制你的 MCP 服务器 URL 并添加到他们的工具中。
3. 用户即可通过其工具访问你的文档和 API 端点。

以下是一些你可以帮助用户连接到你的 MCP 服务器的方法：

Contextual menu

在上下文菜单中为用户添加选项，使其可从文档任意页面连接到你的 MCP 服务器。

选项	标识符	说明
复制 MCP 服务器 URL	mcp	将你的 MCP 服务器 URL 复制到用户的剪贴板。
连接到 Cursor	cursor	在 Cursor 中安装你的 MCP 服务器。
连接到 VS Code	vscode	在 VS Code 中安装你的 MCP 服务器。

Claude

1. 获取你的 MCP 服务器 URL。

   前往控制台，找到你的 MCP 服务器 URL。

2. 为用户发布 MCP 服务器 URL。

   为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Claude 的步骤。

   1. 在 Claude 设置中，前往 Connectors 页面。
   2. 选择 Add custom connector。
   3. 添加你的 MCP 服务器名称和 URL。
   4. 选择 Add。
   5. 使用 Claude 时，选择附件按钮（加号图标）。
   6. 选择你的 MCP 服务器。

详见 Model Context Protocol 文档。

Claude Code

1. 获取你的 MCP 服务器 URL。

   前往控制台，找到你的 MCP 服务器 URL。

2. 为用户发布 MCP 服务器 URL。

   为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Claude Code 的命令。

   claude mcp add --transport http <name> <url>
   

详见 Claude Code 文档。

Cursor

1. 获取你的 MCP 服务器 URL。

   前往控制台，找到你的 MCP 服务器 URL。

2. 为用户发布 MCP 服务器 URL。

   为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Cursor 的步骤。

   1. 使用 Command + Shift + P（Windows 上为 Ctrl + Shift + P）打开命令面板。
   2. 搜索 “Open MCP settings”。
   3. 选择 Add custom MCP。将打开 mcp.json 文件。
   4. 在 mcp.json 中配置服务器：

   {
     "mcpServers": {
       "<your-mcp-server-name>": {
         "url": "<your-mcp-server-url>"
       }
     }
   }
   

详见 Cursor 文档。

VS Code

1. 获取你的 MCP 服务器 URL。

   前往控制台，找到你的 MCP 服务器 URL。

2. 为用户发布 MCP 服务器 URL。

   为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 VS Code 的步骤。

   1. 创建 .vscode/mcp.json 文件。
   2. 在 mcp.json 中配置服务器：

   {
     "servers": {
       "<your-mcp-server-name>": {
         "type": "http",
         "url": "<your-mcp-server-url>"
       }
     }
   }
   

详见 VS Code 文档。

​

示例：连接 Mintlify MCP 服务器

连接 Mintlify MCP 服务器以与 Mintlify API 交互并搜索我们的文档。这样你就能在本地环境中更精准地了解如何使用 Mintlify，同时也演示了如何帮助你的用户连接到你的 MCP 服务器。

Contextual menu

在本页顶部打开上下文菜单，选择 Connect to Cursor 或 Connect to VS Code，即可将 Mintlify MCP 服务器连接到你选择的 IDE。

Claude

在 Claude 中使用 Mintlify MCP 服务器：

1. 将 Mintlify MCP 服务器添加到 Claude

   1. 进入 Claude 设置中的 Connectors 页面。
   2. 选择 Add custom connector。
   3. 添加 Mintlify MCP 服务器：

   • Name: Mintlify
   • URL: https://mintlify.com/docs/mcp

   4. 选择 Add。
2. 在聊天中访问 MCP 服务器

   1. 使用 Claude 时，点击附件按钮（加号图标）。
   2. 选择 Mintlify MCP 服务器。
   3. 向 Claude 提问有关 Mintlify 的问题。

查看 Model Context Protocol 文档了解更多详情。

Claude Code

在 Claude Code 中使用 Mintlify MCP 服务器，运行以下命令：

claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp

通过运行以下命令测试连接：

claude mcp list

查看 Claude Code 文档了解更多详情。

Cursor在 Cursor 中安装

要将 Mintlify MCP 服务器连接到 Cursor，点击 在 Cursor 中安装 按钮。若需手动连接 MCP 服务器，请按以下步骤操作：

1. 打开 MCP 设置

   1. 使用 Command + Shift + P（Windows 上为 Ctrl + Shift + P）打开命令面板。
   2. 搜索 “Open MCP settings”。
   3. 选择 Add custom MCP。这将打开 mcp.json 文件。
2. 配置 Mintlify MCP 服务器

   在 mcp.json 中添加：

   {
     "mcpServers": {
       "Mintlify": {
         "url": "https://mintlify.com/docs/mcp"
       }
     }
   }
   
3. 测试连接

   在 Cursor 的聊天中，输入 “What tools do you have available?”。Cursor 应显示 Mintlify MCP 服务器为可用工具。

查看 Cursor 文档中的 Installing MCP servers 了解更多详情。

VS Code在 VS Code 中安装

要将 Mintlify MCP 服务器连接到 VS Code，点击 在 VS Code 中安装 按钮。若需手动连接 MCP 服务器，创建 .vscode/mcp.json 文件并添加：

{
  "servers": {
    "Mintlify": {
      "type": "http",
      "url": "https://mintlify.com/docs/mcp"
    }
  }
}

查看 VS Code 文档了解更多详情。

​

认证

当你为 MCP 启用某个 API 端点时，服务器会包含在 OpenAPI 的 securitySchemes 和 securityRequirement 中定义的认证要求。任何 key 都由工具直接处理，不会由 Mintlify 存储或处理。

如果用户让其 AI 工具调用受保护的端点，工具会在该时刻向用户请求所需的认证凭据。

​

监控你的 MCP 服务器

你可以在控制台的 MCP Server 页面 的“Available tools”部分查看所有可用的 MCP 工具。

​

故障排查

MCP 服务器仅显示搜索工具

如果你的 MCP 服务器在已有 OpenAPI 规范的情况下仍只显示搜索工具：

1. 检查 OpenAPI 规范是否有效且可访问。
2. 确认已通过 x-mint.mcp.enabled: true 明确为相关端点启用 MCP。
3. 查看部署日志中是否有 OpenAPI 处理错误。

如果 OpenAPI 处理失败，服务器会仅保留搜索工具以确保基本功能可用。

认证问题

如果用户反馈认证相关问题：

1. 检查 OpenAPI 规范是否包含正确的 securitySchemes 定义。
2. 确认已启用的端点能与指定的认证方式正常配合。

工具说明缺失或不清晰

如果 AI 工具未能有效利用你的 API 端点：

1. 为端点补充详细的 summary 和 description 字段。
2. 确保参数名称和说明清晰易懂。
3. 使用 MCP 控制台查看端点作为工具时的呈现效果。