mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
644b17660f
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
350 lines
14 KiB
Plaintext
350 lines
14 KiB
Plaintext
---
|
||
title: "Model Context Protocol（模型上下文协议）"
|
||
description: "使用托管的 MCP 服务器，将文档和 API 端点连接到 AI 工具。"
|
||
keywords: ["MCP", "AI 工具", "Claude", "Cursor"]
|
||
---
|
||
|
||
import { PreviewButton } from "/snippets/previewbutton.jsx"
|
||
|
||
<div id="about-mcp-servers">
|
||
## 关于 MCP 服务器
|
||
</div>
|
||
|
||
Model Context Protocol（MCP，模型上下文协议）是一个开放协议，用于在 AI 应用与外部服务（例如文档）之间建立标准化连接。Mintlify 会基于你的文档生成一个 MCP 服务器，为更广泛的 AI 生态系统做好准备，让任何 MCP 客户端例如 Claude、Cursor、Goose、ChatGPT 等都可以连接到你的文档。
|
||
|
||
你的 MCP 服务器会向 AI 应用提供一个搜索工具，以便在你的文档中发起搜索请求。你的用户必须将你的 MCP 服务器连接到他们的工具中。
|
||
|
||
<div id="how-mcp-servers-work">
|
||
### MCP 服务器的工作方式
|
||
</div>
|
||
|
||
当某个 AI 应用接入你的文档 MCP 服务器后，它可以直接搜索你的文档，而不是在响应用户提示时执行通用的网页搜索。你的 MCP 服务器会提供对文档站点上所有已建立索引内容的访问权限。
|
||
|
||
* AI 应用可以在生成回复时主动搜索你的文档，而不仅仅是在被显式请求时才进行搜索。
|
||
* AI 应用会根据对话的 context 以及你的文档与当前话题的相关性来决定何时使用搜索工具。
|
||
* 每次搜索（工具调用）都发生在生成过程中，因此 AI 应用会从你的文档中检索最新信息来生成回复。
|
||
|
||
<Tip>
|
||
某些 AI 工具（例如 Claude）同时支持 MCP 和 Skills。MCP 让 AI 能够访问你的文档内容，而 Skills 则指导 AI 如何高效使用这些内容。两者是互补的：MCP 提供数据，Skills 提供指令。
|
||
</Tip>
|
||
|
||
<div id="search-filtering-parameters">
|
||
### 搜索筛选参数
|
||
</div>
|
||
|
||
MCP 搜索工具支持可选的筛选参数，AI 应用可以使用它们来缩小搜索结果范围。
|
||
|
||
* **`version`**：将结果筛选为特定的文档版本。例如，`'v0.7'`。只返回带有指定版本标签的内容，或在所有版本中通用的内容。
|
||
* **`language`**：将结果筛选为特定的语言代码。例如，`'en'`、`'zh'` 或 `'es'`。只返回指定语言的内容，或在所有语言中通用的内容。
|
||
* **`apiReferenceOnly`**：当设置为 `true` 时，只返回 API 参考文档页面。
|
||
* **`codeOnly`**：当设置为 `true` 时，只返回代码片段和示例。
|
||
|
||
AI 应用会根据用户查询的上下文来决定何时应用这些筛选条件。例如，如果用户询问特定 API 版本，或请求代码示例，AI 应用可能会自动应用相应的筛选条件，以提供更相关的结果。
|
||
|
||
<div id="mcp-compared-to-web-search">
|
||
### MCP 与网页搜索的对比
|
||
</div>
|
||
|
||
AI 工具可以进行网页搜索，但 MCP 在文档方面具有明显优势。
|
||
|
||
* **直接访问文档来源**：网页搜索依赖搜索引擎已经索引的内容，这些内容可能过时或不完整。MCP 会直接搜索你当前已索引的文档。
|
||
* **集成式工作流**：MCP 允许 AI 在生成回答的过程中执行搜索，而不是先单独进行一次网页搜索。
|
||
* **没有搜索噪音**：SEO（搜索引擎优化）和排序算法会影响网页搜索结果。MCP 则会直接访问你的文档内容。
|
||
|
||
<div id="access-your-mcp-server">
|
||
## 访问你的 MCP 服务器
|
||
</div>
|
||
|
||
<Note>
|
||
仅能为公开文档生成 MCP 服务器。需要终端用户认证的文档无法用于生成服务器。
|
||
</Note>
|
||
|
||
Mintlify 会为你的文档自动生成一个 MCP 服务器，并将其托管在你的文档 URL 的 `/mcp` 路径下。例如，Mintlify 的 MCP 服务器位于 `https://mintlify.com/docs/mcp`。
|
||
|
||
你可以在控制台中的 [MCP 服务器页面](https://dashboard.mintlify.com/products/mcp) 查看并复制你的 MCP 服务器 URL。
|
||
|
||
<Frame>
|
||
<img src="/images/mcp/mcp-server-page-light.png" alt="控制台中的 MCP 服务器页面。" className="block dark:hidden" />
|
||
|
||
<img src="/images/mcp/mcp-server-page-dark.png" alt="控制台中的 MCP 服务器页面。" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<Note>
|
||
托管的 MCP 服务器会在其 URL 中使用 `/mcp` 路径。其他导航元素不能使用 `/mcp` 路径。
|
||
</Note>
|
||
|
||
<div id="content-filtering-and-indexing">
|
||
## 内容过滤与索引编入
|
||
</div>
|
||
|
||
你的 MCP 服务器会搜索 Mintlify 从你的文档存储库中索引编入的内容。文件处理和搜索索引编入决定了可通过 MCP 服务器访问的内容。
|
||
|
||
<div id="file-processing-with-mintignore">
|
||
### 使用 `.mintignore` 进行文件处理
|
||
</div>
|
||
|
||
如果文件匹配 [.mintignore](/zh/organize/mintignore) 中的模式，Mintlify 不会处理或索引它们。这些文件也无法通过你的 MCP 服务器访问。
|
||
|
||
<div id="search-indexing-with-docsjson">
|
||
### 使用 `docs.json` 配置搜索索引
|
||
</div>
|
||
|
||
默认情况下，Mintlify 只会将包含在 `docs.json` 导航中的页面编入索引，以便通过你的 MCP 服务器进行搜索。
|
||
|
||
除非你选择将所有页面都编入索引，否则 Mintlify 会将[隐藏页面](/zh/organize/hidden-pages)（不在导航中的页面）排除在搜索索引之外。要在 MCP 服务器的搜索结果中包含隐藏页面，请在 `docs.json` 中添加 `seo.indexing` 属性。
|
||
|
||
```json
|
||
"seo": {
|
||
"indexing": "all"
|
||
}
|
||
```
|
||
|
||
要将特定页面排除在搜索索引编入之外，请在其 frontmatter 中添加 `noindex: true`。
|
||
|
||
```mdx
|
||
---
|
||
title: "隐藏页面"
|
||
description: "此页面不在导航中,并且无法通过搜索访问。"
|
||
noindex: true
|
||
---
|
||
```
|
||
|
||
<div id="use-your-mcp-server">
|
||
## 使用你的 MCP 服务器
|
||
</div>
|
||
|
||
你的用户需要将你的 MCP 服务器连接到他们常用的 AI 工具。
|
||
|
||
1. 将你的 MCP 服务器 URL 公开可访问。
|
||
2. 让用户复制你的 MCP 服务器 URL 并添加到他们的工具中。
|
||
3. 用户即可通过其工具访问你的文档。
|
||
|
||
以下是一些你可以帮助用户连接到你的 MCP 服务器的方法：
|
||
|
||
<Tabs>
|
||
<Tab title="Contextual menu">
|
||
在[上下文菜单](/zh/ai/contextual-menu)中为用户添加选项，使其可从文档任意页面连接到你的 MCP 服务器。
|
||
|
||
| 选项 | 标识符 | 说明 |
|
||
| :----- | :--------- | :---------- |
|
||
| **复制 MCP 服务器 URL** | `mcp` | 将你的 MCP 服务器 URL 复制到用户的剪贴板。 |
|
||
| **连接到 Cursor** | `cursor` | 在 Cursor 中安装你的 MCP 服务器。 |
|
||
| **连接到 VS Code** | `vscode` | 在 VS Code 中安装你的 MCP 服务器。 |
|
||
</Tab>
|
||
|
||
<Tab title="Claude">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
前往[控制台](https://dashboard.mintlify.com/products/mcp)，找到你的 MCP 服务器 URL。
|
||
</Step>
|
||
|
||
<Step title="为用户发布 MCP 服务器 URL。">
|
||
为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Claude 的步骤。
|
||
|
||
1. 在 Claude 设置中，前往 [Connectors](https://claude.ai/settings/connectors) 页面。
|
||
2. 选择 **Add custom connector**。
|
||
3. 添加你的 MCP 服务器名称和 URL。
|
||
4. 选择 **Add**。
|
||
5. 使用 Claude 时，选择附件按钮（加号图标）。
|
||
6. 选择你的 MCP 服务器。
|
||
</Step>
|
||
</Steps>
|
||
|
||
详见 [Model Context Protocol 文档](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server)。
|
||
</Tab>
|
||
|
||
<Tab title="Claude Code">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
前往[控制台](https://dashboard.mintlify.com/products/mcp)，找到你的 MCP 服务器 URL。
|
||
</Step>
|
||
|
||
<Step title="为用户发布 MCP 服务器 URL。">
|
||
为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Claude Code 的命令。
|
||
|
||
```bash
|
||
claude mcp add --transport http <name> <url>
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
详见 [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers)。
|
||
</Tab>
|
||
|
||
<Tab title="Cursor">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
前往[控制台](https://dashboard.mintlify.com/products/mcp)，找到你的 MCP 服务器 URL。
|
||
</Step>
|
||
|
||
<Step title="为用户发布 MCP 服务器 URL。">
|
||
为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Cursor 的步骤。
|
||
|
||
1. 使用 <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>（Windows 上为 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>）打开命令面板。
|
||
2. 搜索 "Open MCP settings"。
|
||
3. 选择 **Add custom MCP**。这会打开 `mcp.json` 文件。
|
||
4. 在 `mcp.json` 中配置服务器：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"<your-mcp-server-name>": {
|
||
"url": "<your-mcp-server-url>"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
详见 [Cursor 文档](https://docs.cursor.com/en/context/mcp#installing-mcp-servers)。
|
||
</Tab>
|
||
|
||
<Tab title="VS Code">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
前往[控制台](https://dashboard.mintlify.com/products/mcp)，找到你的 MCP 服务器 URL。
|
||
</Step>
|
||
|
||
<Step title="为用户发布 MCP 服务器 URL。">
|
||
为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 VS Code 的步骤。
|
||
|
||
1. 创建 `.vscode/mcp.json` 文件。
|
||
2. 在 `mcp.json` 中配置服务器：
|
||
|
||
```json
|
||
{
|
||
"servers": {
|
||
"<your-mcp-server-name>": {
|
||
"type": "http",
|
||
"url": "<your-mcp-server-url>"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
详见 [VS Code 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<div id="example-connect-to-the-mintlify-mcp-server">
|
||
### 示例：连接 Mintlify MCP 服务器
|
||
</div>
|
||
|
||
连接 Mintlify MCP 服务器，以便在你常用的 AI 工具中搜索此文档站点。这样你就能在本地环境中更精准地了解如何使用 Mintlify，同时也演示了如何帮助你的用户连接到你的 MCP 服务器。
|
||
|
||
<Tabs>
|
||
<Tab title="Contextual menu">
|
||
在本页顶部打开上下文菜单，选择 **Connect to Cursor** 或 **Connect to VS Code**，即可将 Mintlify MCP 服务器连接到你选择的 IDE。
|
||
</Tab>
|
||
|
||
<Tab title="Claude">
|
||
在 Claude 中使用 Mintlify MCP 服务器：
|
||
|
||
<Steps>
|
||
<Step title="将 Mintlify MCP 服务器添加到 Claude">
|
||
1. 进入 Claude 设置中的 [Connectors](https://claude.ai/settings/connectors) 页面。
|
||
2. 选择 **Add custom connector**。
|
||
3. 添加 Mintlify MCP 服务器：
|
||
|
||
* Name: `Mintlify`
|
||
* URL: `https://mintlify.com/docs/mcp`
|
||
|
||
4. 选择 **Add**。
|
||
</Step>
|
||
|
||
<Step title="在聊天中访问 MCP 服务器">
|
||
1. 使用 Claude 时，点击附件按钮（加号图标）。
|
||
2. 选择 Mintlify MCP 服务器。
|
||
3. 向 Claude 提问有关 Mintlify 的问题。
|
||
</Step>
|
||
</Steps>
|
||
|
||
查看 [Model Context Protocol 文档](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server)了解更多详情。
|
||
</Tab>
|
||
|
||
<Tab title="Claude Code">
|
||
在 Claude Code 中使用 Mintlify MCP 服务器，运行以下命令：
|
||
|
||
```bash
|
||
claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp
|
||
```
|
||
|
||
通过运行以下命令测试连接：
|
||
|
||
```bash
|
||
claude mcp list
|
||
```
|
||
|
||
查看 [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers)了解更多详情。
|
||
</Tab>
|
||
|
||
<Tab title="Cursor">
|
||
<PreviewButton href="cursor://anysphere.cursor-deeplink/mcp/install?name=mintlify&config=eyJ1cmwiOiJodHRwczovL21pbnRsaWZ5LmNvbS9kb2NzL21jcCJ9">在 Cursor 中安装</PreviewButton>
|
||
|
||
要将 Mintlify MCP 服务器连接到 Cursor，点击 **在 Cursor 中安装** 按钮。若需手动连接 MCP 服务器，请按以下步骤操作：
|
||
|
||
<Steps>
|
||
<Step title="打开 MCP 设置">
|
||
1. 使用 <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>（Windows 上为 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>）打开命令面板。
|
||
2. 搜索 “Open MCP settings”。
|
||
3. 选择 **Add custom MCP**。这会打开 `mcp.json` 文件。
|
||
</Step>
|
||
|
||
<Step title="配置 Mintlify MCP 服务器">
|
||
在 `mcp.json` 中添加：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"Mintlify": {
|
||
"url": "https://mintlify.com/docs/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Step>
|
||
|
||
<Step title="测试连接">
|
||
在 Cursor 的聊天中，输入 “What tools do you have available?”。Cursor 应显示 Mintlify MCP 服务器为可用工具。
|
||
</Step>
|
||
</Steps>
|
||
|
||
查看 Cursor 文档中的 [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) 了解更多详情。
|
||
</Tab>
|
||
|
||
<Tab title="VS Code">
|
||
<PreviewButton href="https://vscode.dev/redirect/mcp/install?name=mintlify&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmintlify.com%2Fdocs%2Fmcp%22%7D">在 VS Code 中安装</PreviewButton>
|
||
|
||
要将 Mintlify MCP 服务器连接到 VS Code，点击 **在 VS Code 中安装** 按钮。若需手动连接 MCP 服务器，创建 `.vscode/mcp.json` 文件并添加：
|
||
|
||
```json
|
||
{
|
||
"servers": {
|
||
"Mintlify": {
|
||
"type": "http",
|
||
"url": "https://mintlify.com/docs/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
查看 [VS Code 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)了解更多详情。
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<div id="using-multiple-mcp-servers">
|
||
### 使用多个 MCP 服务器
|
||
</div>
|
||
|
||
用户可以将多个 MCP 服务器连接到他们的 AI 工具。已连接的 MCP 服务器在 AI 调用搜索工具之前不会消耗上下文。AI 会根据查询的相关性决定何时进行搜索，因此不会为每个问题都搜索所有已连接的服务器。
|
||
|
||
当 AI 执行搜索时，每次查询都会返回多个结果，并被添加到对话的上下文中。如果 AI 为单个问题搜索多个服务器，就可能会占用大量上下文。
|
||
|
||
使用多个 MCP 服务器的最佳实践：
|
||
|
||
* 只连接与当前工作相关的 MCP 服务器。
|
||
* 在提示中尽量具体，这样 AI 会搜索到最相关的服务器。
|
||
* 断开当前未主动使用的服务器，以减少潜在的上下文占用。 |