Model Context Protocol（模型上下文协议）

使用托管的 MCP 服务器，将文档和 API 端点连接到 AI 工具。

​

关于 MCP 服务器

Model Context Protocol (MCP，模型上下文协议) 是一个开放协议，用于在 AI 应用与外部服务 (例如文档) 之间建立标准化连接。Mintlify 会基于你的文档生成一个 MCP 服务器，为更广泛的 AI 生态系统做好准备，让任何 MCP 客户端例如 Claude、Cursor、Goose、ChatGPT 等都可以连接到你的文档。

你的 MCP 服务器会向 AI 应用提供一个搜索工具，以便在你的文档中发起搜索请求。你的用户必须将你的 MCP 服务器连接到他们的工具中。

​

MCP 服务器的工作方式

当某个 AI 应用接入你的文档 MCP 服务器后，它可以直接根据用户提示搜索你的文档，而不是依赖其训练数据中的信息或执行通用的网页搜索。你的 MCP 服务器会提供对文档站点上所有已建立索引内容的访问权限。

• AI 应用可以在生成回复时主动搜索你的文档，即使没有被明确要求搜索你的文档来获取答案。
• AI 应用会根据对话的 context 以及你的文档与当前话题的相关性来决定何时使用搜索工具。
• 每次搜索 (也称为一次工具调用) 都发生在生成过程中，因此 AI 应用会从你的文档中检索最新信息来生成回复。

某些 AI 工具 (例如 Claude) 同时支持 MCP 和 Skills。MCP 让 AI 能够访问你的文档内容，而 Skills 则指导 AI 如何高效使用这些内容。两者是互补的：MCP 提供数据，Skills 提供指令。

​

搜索筛选参数

MCP 搜索工具支持可选的筛选参数，AI 应用使用它们来缩小搜索结果范围。

• version：将结果筛选为特定的文档版本。例如，'v0.7'。只返回带有指定版本标签的内容，或在所有版本中通用的内容。
• language：将结果筛选为特定的语言代码。例如，'en'、'zh' 或 'es'。只返回指定语言的内容，或在所有语言中通用的内容。

AI 应用会根据用户 query 的上下文来决定何时应用这些筛选条件。例如，如果用户询问特定 API 版本，AI 应用可能会自动应用相应的筛选条件，以提供更相关的结果。

​

MCP 与网页搜索的对比

AI 工具可以进行网页搜索，但 MCP 在文档方面具有明显优势。

• 直接访问文档来源：网页搜索依赖搜索引擎已经索引的内容，这些内容可能过时或不完整。MCP 会直接搜索你当前已索引的文档。
• 集成式工作流：MCP 允许 AI 在生成回答的过程中执行搜索，而不是先单独进行一次网页搜索。
• 没有搜索噪音：SEO (搜索引擎优化) 和排序算法会影响网页搜索结果。MCP 则会直接访问你的文档内容。

​

访问你的 MCP 服务器

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

• 对于公开文档，你的 MCP 服务器对任何人都可用。它会搜索所有已编入索引的公开页面。
• 对于部分需要认证的文档，也就是某些页面公开、其他页面需要登录的情况，你必须先启用你的 MCP 服务器，用户才能访问它。未认证的用户可以搜索公开内容。已完成认证的用户可以根据其 user groups 搜索他们有权访问的所有内容。
• 对于所有页面都需要认证的文档，你必须先启用你的 MCP 服务器，用户才能使用它。用户必须先完成认证，然后才能连接到你的 MCP 服务器。你的 MCP 服务器只会根据每个用户有权访问的 user groups 搜索相应内容。

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

托管的 MCP 服务器使用 /mcp 和 /authed/mcp 路径。其他导航元素不能使用这些路径。

​

启用 MCP 认证

如果你的文档需要认证，你的 MCP 服务器会要求用户在连接前先完成认证。当用户将你的 MCP 服务器 URL 添加到其 AI 工具时，必须使用现有凭据登录。认证完成后，系统会通过重定向将用户带回其工具。MCP 服务器只会根据每位用户的用户组返回其有权访问的内容。

如果你的文档采用部分认证，同时包含公开页面和受保护页面，你有两个 MCP 服务器端点：

• /mcp：无需认证。仅返回公开内容。将此端点分享给需要访问公开内容的用户。
• /authed/mcp：始终需要认证。根据每位用户的用户组权限返回相应内容。将此端点分享给需要访问受保护内容的用户。

/authed/mcp 端点使用其专属的 OAuth 流程，位于 /authed/mcp/oauth/*。为你的 MCP 服务器配置的重定向域名同时适用于 /mcp 和 /authed/mcp。

默认情况下，你的 MCP 服务器仅适用于 localhost 工具。要允许基于 Web 的工具和桌面客户端连接，请配置允许的 OAuth 重定向 URI。重定向 URI 是用户完成认证后 AI 工具使用的地址。如果用户的 AI 工具的重定向 URI 未被允许，就无法完成认证。

1. 在你的控制台中启用 MCP 认证

   1. 前往你的控制台中的 MCP 服务器页面。
   2. 点击 Enable MCP Server 开关。
2. 启用预定义客户端

   控制台包含常见 AI 工具（如 Claude Desktop 和 Cursor）的预定义开关。为你想要允许的每个客户端启用开关。每个开关会自动添加该客户端相应的重定向 URI。

3. 添加自定义域名

   对于未列为预定义客户端的 AI 工具，请在 Custom Domains 部分添加其重定向域名。输入重定向域名的主机名（例如 example.com）。如果用户的 AI 工具的重定向域名不在此列表中，就无法完成认证。

   回环地址 (localhost、127.0.0.1) 始终受信任，无需添加。

​

速率限制

为保护可用性，Mintlify 会对 MCP 服务器实施速率限制。

范围	限制	说明
每位用户 (IP 地址)	每小时 5,000 个请求	限制单个用户搜索你的文档的频率。
每个文档站点 (domain)	每小时 1,000 个请求	限制所有用户在你的 MCP 服务器上的总搜索次数。

​

内容过滤与索引编入

你的 MCP 服务器会搜索 Mintlify 从你的文档存储库中索引编入的内容。文件处理和搜索索引编入控制了通过你的 MCP 服务器可用的内容。

对于需要身份验证的文档，你的 MCP 服务器只会索引编入公开用户组中的页面。对于采用部分身份验证的文档，你的 MCP 服务器会为未经身份验证的用户索引编入公开页面，以及公开用户组中的任何页面。

​

使用 .mintignore 进行文件处理

如果文件匹配 .mintignore 中的模式，Mintlify 不会处理或索引它们。这些文件也无法通过你的 MCP 服务器访问。

​

使用 docs.json 配置搜索索引

默认情况下，Mintlify 只会将包含在 docs.json 导航中的页面编入索引，以便通过你的 MCP 服务器进行搜索。

除非你选择将所有页面都编入索引，否则 Mintlify 会将隐藏页面 (不在导航中的页面) 排除在搜索索引之外。要在 MCP 服务器的搜索结果中包含隐藏页面，请在 docs.json 中添加 seo.indexing 属性。

"seo": {
    "indexing": "all"
}

要将特定页面排除在搜索索引编入之外，请在其 frontmatter 中添加 noindex: true。

---
title: "隐藏页面"
description: "此页面不在导航中,并且无法通过搜索访问。"
noindex: true
---

​

使用你的 MCP 服务器

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

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

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

Contextual menu

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

选项	标识符	说明
复制 MCP 服务器 URL	mcp	将你的 MCP 服务器 URL 复制到用户的剪贴板。
复制 MCP 安装命令	add-mcp	将用于安装 MCP 服务器的 npx add-mcp 命令复制到用户的剪贴板。
连接到 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 服务器，以便在你常用的 AI 工具中搜索此文档站点。这样你就能在本地环境中更精准地了解如何使用 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

要将 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

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

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

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

​

使用多个 MCP 服务器

用户可以将多个 MCP 服务器连接到其 AI 工具。已连接的 MCP 服务器在 AI 调用搜索工具之前不会占用上下文。AI 会根据查询的相关性决定何时搜索，因此不会针对每个问题搜索每个已连接的服务器。

当 AI 执行搜索时，每次查询都会返回多个结果，这些结果会加入对话上下文。如果 AI 为了回答同一个问题搜索多个服务器，可能会占用大量上下文。

使用多个 MCP 服务器的最佳实践：

• 仅连接与当前工作相关的 MCP 服务器。
• 尽量让提示词更具体，以便 AI 搜索最相关的服务器。
• 断开未在主动使用的服务器，以减少潜在的上下文占用。