mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
1bfbfe8f88
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
660 lines
30 KiB
Plaintext
660 lines
30 KiB
Plaintext
---
|
||
title: "Model Context Protocol (MCP)（模型上下文协议）"
|
||
description: "将 Claude、Cursor、ChatGPT 等 AI 工具连接到托管的搜索 MCP 服务器，让它们能够搜索并检索你站点上的文档内容和 API 端点。"
|
||
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 服务器连接到他们的工具中。
|
||
|
||
<Tip>
|
||
想要让代理编辑你的内容，而不只是读取？请参阅 [Mintlify MCP 服务器](/ai/mintlify-mcp)，这是一个已认证的 MCP 服务器，会向受信任的代理公开 branching、页面编辑、导航和 `docs.json` 工具。
|
||
</Tip>
|
||
|
||
<div id="how-mcp-servers-work">
|
||
### MCP 服务器的工作方式
|
||
</div>
|
||
|
||
当某个 AI 应用接入你的文档 MCP 服务器后，它可以直接根据用户提示搜索你的文档并获取完整页面内容，而不是依赖其训练数据中的信息或执行通用的网页搜索。你的 MCP 服务器会提供对文档站点上所有已建立索引内容的访问权限。
|
||
|
||
* AI 应用可以在生成回复时主动搜索你的文档，即使没有被明确要求搜索你的文档来获取答案。
|
||
* AI 应用会根据对话的上下文以及你的文档与当前话题的相关性来决定何时使用可用的工具。
|
||
* 每次工具调用都发生在生成过程中，因此 AI 应用会利用你的文档中的最新信息来生成回复。
|
||
|
||
<Tip>
|
||
某些 AI 工具 (例如 Claude) 同时支持 MCP 和 skills。MCP 提供对文档内容的访问，而 skills 则指导代理如何高效使用这些内容。两者是互补的，连接你的 MCP 服务器即可让代理同时获得这两者。
|
||
</Tip>
|
||
|
||
<div id="mcp-tools">
|
||
### MCP 工具
|
||
</div>
|
||
|
||
你的 MCP 服务器提供三个代理可以使用的工具：
|
||
|
||
- **Search**：在你的文档中搜索相关内容，返回带有标题和链接的摘要片段。使用此工具来发现信息或查找与查询匹配的页面。
|
||
- **Query docs filesystem**：使用 shell 风格的命令读取和浏览文档的虚拟文件系统。使用此工具来获取页面内容、浏览文档结构或提取特定部分——包括在单次调用中批量读取多个页面。
|
||
- **Submit feedback**：当代理发现某个页面不正确、过时、令人困惑或不完整时，将文档问题反馈给你的团队。代理会提供页面路径和问题描述，Mintlify 会将其记录为分析仪表板中的负面反馈。
|
||
|
||
代理会根据对话的上下文来决定何时使用每个工具。例如，代理可能会先搜索你的文档以查找相关页面，然后使用 query docs filesystem 工具读取最相关结果的完整内容。如果它在过程中发现页面存在问题，可以提交反馈。
|
||
|
||
<div id="mcp-resources">
|
||
### MCP 资源
|
||
</div>
|
||
|
||
你的 MCP 服务器还会将你的 [skill.md 文件](/zh/ai/skillmd)作为 MCP 资源公开。连接到你的 MCP 服务器的代理可以发现并访问你的 skill 文件，无需单独安装。
|
||
|
||
`Skill.md` 资源会显示在 MCP 服务器的资源列表中，包含 Mintlify 生成的或你在[自定义 skill 文件](/zh/ai/skillmd#custom-skill-files)中定义的能力描述。
|
||
|
||
如果你的文档启用了[身份验证](/zh/deploy/authentication-setup)，带有 `groups` 字段的技能仅会向组匹配的已认证终端用户开放。参见[将技能限制为特定用户组](/zh/ai/skillmd#restrict-skills-to-user-groups)。
|
||
|
||
<div id="search-parameters">
|
||
### 搜索参数
|
||
</div>
|
||
|
||
MCP 搜索工具支持可选参数，AI 应用使用它们来控制和优化搜索结果。
|
||
|
||
* **`version`**：将结果筛选为特定的文档版本。例如，`'v0.7'`。仅在你的文档包含多个版本时可用。只返回带有指定版本标签的内容，或在所有版本中通用的内容。
|
||
* **`language`**：将结果筛选为特定的语言代码。例如，`'en'`、`'zh'` 或 `'es'`。仅在你的文档包含多种语言时可用。只返回指定语言的内容，或在所有语言中通用的内容。
|
||
|
||
AI 应用会根据用户 query 的上下文来决定何时应用这些参数。例如，如果用户询问特定 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>
|
||
|
||
Mintlify 会为你的文档生成一个 MCP 服务器，并将其托管在你的文档 URL 的 `/mcp` 路径下。例如，Mintlify 的 MCP 服务器位于 `https://mintlify.com/docs/mcp`。
|
||
|
||
* 对于公开文档，你的 MCP 服务器对任何人都可用。它会搜索所有已编入索引的公开页面。
|
||
* 对于部分需要认证的文档，也就是某些页面公开、其他页面需要登录的情况，你必须先启用你的 MCP 服务器，用户才能访问它。未认证的用户可以搜索公开内容。已完成认证的用户可以根据其 [user groups](/zh/deploy/authentication-setup) 搜索他们有权访问的所有内容。
|
||
* 对于所有页面都需要认证的文档，你必须先启用你的 MCP 服务器，用户才能使用它。用户必须先完成认证，然后才能连接到你的 MCP 服务器。你的 MCP 服务器只会根据每个用户有权访问的 [user groups](/zh/deploy/authentication-setup) 搜索相应内容。
|
||
|
||
如果启用了认证，请在控制台的 **Settings → Security & access → MCP** 中配置你的托管 Search MCP 服务器。已认证的 Search MCP 服务器位于你的站点 URL 的 `/authed/mcp` 路径。
|
||
|
||
<Note>
|
||
仅当你为站点启用了[认证](/zh/deploy/authentication-setup)时，**MCP** 设置页面才会显示。如果你的站点不需要认证，你的 Search MCP 服务器仍可通过站点 URL 的 `/mcp` 路径访问。
|
||
</Note>
|
||
|
||
<Note>
|
||
托管的 MCP 服务器使用 `/mcp` 和 `/authed/mcp` 路径。其他导航元素不能使用这些路径。
|
||
</Note>
|
||
|
||
<div id="discovery-endpoint">
|
||
### 发现端点
|
||
</div>
|
||
|
||
Mintlify 在 `/.well-known/mcp` 托管一个发现文档，便于智能体和工具在无需预先配置的情况下定位你的 MCP 服务器。
|
||
|
||
`GET /.well-known/mcp` 会返回一个描述你的 MCP 服务器的 JSON 文档：
|
||
|
||
```json
|
||
{
|
||
"version": "1.0.0",
|
||
"transport": "http",
|
||
"url": "https://your-docs.com/mcp",
|
||
"servers": [
|
||
{
|
||
"name": "public",
|
||
"url": "https://your-docs.com/mcp",
|
||
"transport": "http",
|
||
"authentication": "none"
|
||
},
|
||
{
|
||
"name": "authenticated",
|
||
"url": "https://your-docs.com/authed/mcp",
|
||
"transport": "http",
|
||
"authentication": "oauth2"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `version` | MCP 服务器版本。 |
|
||
| `transport` | 传输协议。始终为 `http`。 |
|
||
| `url` | 默认的公开 MCP 服务器 URL。 |
|
||
| `servers` | 可用的 MCP 服务器。始终包含 `public` 条目。当你的站点启用了身份验证时，还会包含 `authenticated` 条目。 |
|
||
| `servers[].name` | 服务器条目的标识符。 |
|
||
| `servers[].authentication` | 服务器条目的身份验证方式。 |
|
||
|
||
为了便于智能体直接使用，相同的发现文档也可在 `/.well-known/mcp.json` 获取。此外，Mintlify 还会在 `/.well-known/mcp/server-card.json` 提供一个 MCP 服务器卡片，并在 `/.well-known/mcp/server-cards.json` 提供服务器卡片列表。所有发现端点均会自动提供，无需任何配置。
|
||
|
||
<div id="server-card-endpoints">
|
||
#### 服务器卡片端点
|
||
</div>
|
||
|
||
`GET /.well-known/mcp/server-card.json` 返回一个描述你的 MCP 服务器的单个服务器卡片。`GET /.well-known/mcp/server-cards.json` 返回一个 `servers` 数组，其中每个可用端点对应一个卡片（始终包含一个公开服务器卡片；当启用身份验证时，还会包含一个已认证的服务器卡片）。
|
||
|
||
每个服务器卡片都包含标准的发现字段以及一个 `tools` 数组，用于描述该服务器对外公布的 MCP 工具。你可以借助此信息在 MCP 客户端中预先填充工具元数据，而无需向服务器发起 `initialize` 调用。
|
||
|
||
```json
|
||
{
|
||
"name": "your-docs-search",
|
||
"version": "1.0.0",
|
||
"url": "https://your-docs.com/mcp",
|
||
"transport": "http",
|
||
"description": "Search and retrieve your documentation",
|
||
"capabilities": {
|
||
"tools": true,
|
||
"resources": true
|
||
},
|
||
"authentication": "none",
|
||
"tools": [
|
||
{
|
||
"name": "search_your_docs",
|
||
"title": "Search documentation",
|
||
"description": "Search across your documentation site.",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"query": { "type": "string", "description": "Search query" }
|
||
},
|
||
"required": ["query"]
|
||
},
|
||
"annotations": {
|
||
"readOnlyHint": true,
|
||
"destructiveHint": false,
|
||
"idempotentHint": true,
|
||
"openWorldHint": false
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `tools[].name` | 通过 MCP 对外公布的工具名称。工具名称因站点而异，请使用发现端点返回的值，而不要硬编码。 |
|
||
| `tools[].title` | 工具的可选人类可读标题。 |
|
||
| `tools[].description` | 工具功能的人类可读描述。 |
|
||
| `tools[].inputSchema` | 工具输入参数的 JSON Schema。 |
|
||
| `tools[].annotations` | 可选的 [MCP 工具注解](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)，用于描述工具的行为特征。 |
|
||
|
||
内置的搜索和查询文档文件系统工具会以只读且非破坏性的方式对外公布，并带有以下注解：
|
||
|
||
- `readOnlyHint: true`—该工具不会修改任何状态。
|
||
- `destructiveHint: false`—该工具没有破坏性副作用。
|
||
- `idempotentHint: true`—使用相同参数重复调用会返回等价的结果。
|
||
- `openWorldHint: false`—该工具针对你已索引的文档进行操作，而非开放的互联网。
|
||
|
||
MCP 客户端可以利用这些注解向用户呈现工具的安全性信息，或允许只读工具在无需显式批准的情况下运行。
|
||
|
||
<div id="enable-authenticated-mcp">
|
||
### 启用 MCP 认证
|
||
</div>
|
||
|
||
如果你的文档需要认证，你的 MCP 服务器会要求用户在连接前先完成认证。当用户将你的 MCP 服务器 URL 添加到其 AI 工具时，必须使用现有凭据登录。认证完成后，系统会通过重定向将用户带回其工具。MCP 服务器只会根据每位用户的[用户组](/zh/deploy/authentication-setup)返回其有权访问的内容。
|
||
|
||
如果你的文档采用部分认证，同时包含公开页面和受保护页面，你有两个 MCP 服务器端点：
|
||
|
||
- `/mcp`：无需认证。仅返回公开内容。将此端点分享给需要访问公开内容的用户。
|
||
- `/authed/mcp`：始终需要认证。根据每位用户的[用户组](/zh/deploy/authentication-setup)权限返回相应内容。将此端点分享给需要访问受保护内容的用户。
|
||
|
||
`/authed/mcp` 端点使用其专属的 OAuth 流程，位于 `/authed/mcp/oauth/*`。为你的 MCP 服务器配置的重定向域名同时适用于 `/mcp` 和 `/authed/mcp`。
|
||
|
||
Claude、ChatGPT、Cursor 和 Devin 等常见 MCP 客户端始终被允许对你的 MCP 服务器完成认证。你无需将这些客户端添加到任何允许列表。
|
||
|
||
要允许其他基于 Web 的工具连接，请在控制台中添加它们的重定向域名。重定向域名是指用户完成认证后，AI 工具使用的主机名。如果用户的 AI 工具的重定向域名不在此列表中，且该工具不属于始终允许的客户端，就无法完成认证。
|
||
|
||
当你的站点配置了[认证](/zh/deploy/authentication-setup)时，托管 MCP 服务器会自动启用。
|
||
|
||
<Steps>
|
||
<Step title="打开托管 MCP 设置">
|
||
在控制台中，前往 **Settings → Security & access → MCP**。
|
||
</Step>
|
||
|
||
<Step title="添加自定义重定向域名">
|
||
在 **Allowed OAuth redirect URIs** 下，添加你希望向用户开放访问权限的其他 AI 工具的重定向域名。你只需为不在始终允许列表中的客户端添加域名。
|
||
|
||
默认情况下，重定向域名使用 `https://`。要允许自定义协议方案，请在域名条目中包含完整协议。例如，原生应用回调如 `myapp://callback`。Mintlify 始终阻止危险协议，如 `javascript:`、`data:` 和 `file:`。
|
||
|
||
回环地址 (`localhost`、`127.0.0.1`) 始终受信任，无需添加。
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="client-credentials">
|
||
### 客户端凭据
|
||
</div>
|
||
|
||
客户端凭据允许你以编程方式连接到你的认证 MCP 服务器，无需基于浏览器的登录。客户端凭据适用于服务端集成、CI/CD 流水线、自动化工作流以及用户无法完成交互式 OAuth 流程的任何环境。
|
||
|
||
客户端凭据通过 `/authed/mcp` 端点进行认证，并返回所有公开页面以及未限制为特定用户组的认证页面的全部内容。
|
||
|
||
<Steps>
|
||
<Step title="创建客户端凭据">
|
||
1. 在控制台中，前往 **Settings → Security & access → MCP**。
|
||
2. 在 **Client credentials** 部分，单击 **Generate**。
|
||
3. 输入凭据标签以标识其用途，然后确认。
|
||
4. 从 **Secret generated** 对话框复制 **client ID** 和 **client secret**。client secret 只显示一次，之后无法找回。
|
||
</Step>
|
||
<Step title="用凭据换取访问令牌">
|
||
向你的 MCP 服务器的令牌端点发送 POST 请求，附上你的 client ID 和 secret。令牌端点位于你的文档 URL 的 `/authed/mcp/oauth/token` 路径下。
|
||
|
||
<CodeGroup>
|
||
```bash cURL
|
||
curl -X POST https://your-docs.com/authed/mcp/oauth/token \
|
||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||
-d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
|
||
```
|
||
|
||
```bash cURL (Basic Auth)
|
||
curl -X POST https://your-docs.com/authed/mcp/oauth/token \
|
||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||
-H 'Authorization: Basic BASE64_CLIENT_ID_COLON_SECRET' \
|
||
-d 'grant_type=client_credentials'
|
||
```
|
||
</CodeGroup>
|
||
|
||
响应中包含一个访问令牌和一个刷新令牌：
|
||
|
||
```json
|
||
{
|
||
"access_token": "eyJhbGciOi...",
|
||
"token_type": "Bearer",
|
||
"expires_in": 1209600,
|
||
"refresh_token": "eyJhbGciOi...",
|
||
"scope": "mcp:search"
|
||
}
|
||
```
|
||
|
||
访问令牌在 `expires_in` 指定的秒数后过期。当前令牌过期后，请使用 `refresh_token` 获取新的访问令牌。
|
||
</Step>
|
||
<Step title="连接到 MCP 服务器">
|
||
连接到 `/authed/mcp` 端点时，将访问令牌用作 bearer token。
|
||
|
||
<CodeGroup>
|
||
```bash cURL
|
||
curl -X POST https://your-docs.com/authed/mcp \
|
||
-H 'Authorization: Bearer ACCESS_TOKEN' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Accept: application/json, text/event-stream' \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "initialize",
|
||
"params": {
|
||
"protocolVersion": "2025-03-26",
|
||
"capabilities": {},
|
||
"clientInfo": {"name": "my-integration", "version": "1.0.0"}
|
||
}
|
||
}'
|
||
```
|
||
|
||
```bash Claude Code
|
||
claude mcp add --transport http \
|
||
--header "Authorization: Bearer ACCESS_TOKEN" \
|
||
my-docs https://your-docs.com/authed/mcp
|
||
```
|
||
</CodeGroup>
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="managing-client-credentials">
|
||
#### 管理客户端凭据
|
||
</div>
|
||
|
||
你可以在控制台的 **Settings → Security & access → MCP** 管理你的客户端凭据。
|
||
|
||
- **删除凭据**将永久撤销访问权限。此操作无法撤消。
|
||
- **轮换凭据**的方式是：先创建一个新凭据，将所有使用旧凭据的集成更新为新的 client ID 和 secret，然后删除旧凭据。每个凭据都有唯一的 secret，因此在删除旧凭据之前，创建新凭据不会影响现有凭据。
|
||
|
||
<Warning>
|
||
请像对待密码一样对待 client secret。不要将它们提交到源代码管理中，也不要在客户端代码中暴露它们。请使用环境变量或密钥管理器来存储它们。
|
||
</Warning>
|
||
|
||
<div id="rate-limits">
|
||
### 速率限制
|
||
</div>
|
||
|
||
为保护可用性，Mintlify 会对 MCP 服务器实施速率限制。
|
||
|
||
| 范围 | 限制 | 说明 |
|
||
| :-------------- | :------------ | :------------------------ |
|
||
| 每位用户 (IP 地址) | 每小时 5,000 个请求 | 限制单个用户查询你的 MCP 服务器配置的频率。 |
|
||
| 每个文档站点的 Search (domain) | 每小时 10,000 个请求 | 限制所有用户在你的 MCP 服务器上的搜索工具调用总次数。 |
|
||
| 每个文档站点的 Query docs filesystem (domain) | 每小时 10,000 个请求 | 限制所有用户在你的 MCP 服务器上的 query docs filesystem 工具调用总次数。 |
|
||
| 每个文档站点的认证 Search (domain) | 每小时 5,000 个请求 | 限制所有用户在你的 MCP 服务器上的认证搜索工具调用总次数。 |
|
||
| 每个文档站点的认证 Query docs filesystem (domain) | 每小时 5,000 个请求 | 限制所有用户在你的 MCP 服务器上的认证 query docs filesystem 工具调用总次数。 |
|
||
|
||
当超过限制时，MCP 服务器会返回 HTTP `429 Too Many Requests` 响应。MCP 客户端应稍作退避后再重试 — 从几秒开始的指数退避是一个安全的默认策略。限制在滚动的每小时窗口中重置，因此大多数调用方都会在一小时内自动恢复。
|
||
|
||
如果你的站点持续触发这些限制，请联系 [support@mintlify.com](mailto:support@mintlify.com) 申请更高的限额。
|
||
|
||
<div id="content-filtering-and-indexing">
|
||
## 内容过滤与索引编入
|
||
</div>
|
||
|
||
你的 MCP 服务器会搜索 Mintlify 从你的文档存储库中索引编入的内容。文件处理和搜索索引编入控制了通过你的 MCP 服务器可用的内容。
|
||
|
||
对于需要身份验证的文档，你的 MCP 服务器会索引[公开页面](/zh/deploy/authentication-setup#make-pages-public)以及已认证用户根据其[用户组](/zh/deploy/authentication-setup#restrict-pages-to-specific-user-groups)有权访问的所有页面。
|
||
|
||
对于采用部分身份验证的文档，未认证用户可以搜索公开页面。已认证用户可以搜索公开页面以及他们根据其用户组有权访问的所有页面。
|
||
|
||
<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 复制到用户的剪贴板。 |
|
||
| **复制 MCP 安装命令** | `add-mcp` | 将用于安装 MCP 服务器的 `npx add-mcp` 命令复制到用户的剪贴板。 |
|
||
| **连接到 Cursor** | `cursor` | 在 Cursor 中安装你的 MCP 服务器。 |
|
||
| **连接到 VS Code** | `vscode` | 在 VS Code 中安装你的 MCP 服务器。 |
|
||
</Tab>
|
||
|
||
<Tab title="Claude">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
你的 MCP 服务器 URL 是站点 URL 的 `/mcp` 路径。例如 `https://your-docs.com/mcp`。如果你的站点需要认证，请改用 `/authed/mcp` 路径。
|
||
</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。">
|
||
你的 MCP 服务器 URL 是站点 URL 的 `/mcp` 路径。例如 `https://your-docs.com/mcp`。如果你的站点需要认证，请改用 `/authed/mcp` 路径。
|
||
</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="Codex">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
你的 MCP 服务器 URL 是站点 URL 的 `/mcp` 路径。例如 `https://your-docs.com/mcp`。如果你的站点需要认证，请改用 `/authed/mcp` 路径。
|
||
</Step>
|
||
|
||
<Step title="为用户发布 MCP 服务器 URL。">
|
||
为用户创建一份指南，包含你的 MCP 服务器 URL 以及将其连接到 Codex CLI 的步骤。
|
||
|
||
在 `~/.codex/config.toml` 中添加：
|
||
|
||
```toml
|
||
[mcp_servers.<your-mcp-server-name>]
|
||
url = "<your-mcp-server-url>"
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
详见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。
|
||
</Tab>
|
||
|
||
<Tab title="Cursor">
|
||
<Steps>
|
||
<Step title="获取你的 MCP 服务器 URL。">
|
||
你的 MCP 服务器 URL 是站点 URL 的 `/mcp` 路径。例如 `https://your-docs.com/mcp`。如果你的站点需要认证，请改用 `/authed/mcp` 路径。
|
||
</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。">
|
||
你的 MCP 服务器 URL 是站点 URL 的 `/mcp` 路径。例如 `https://your-docs.com/mcp`。如果你的站点需要认证，请改用 `/authed/mcp` 路径。
|
||
</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="Codex">
|
||
要将 Mintlify MCP 服务器连接到 Codex CLI，请将其添加到位于 `~/.codex/config.toml` 的配置文件中：
|
||
|
||
```toml
|
||
[mcp_servers.mintlify]
|
||
url = "https://mintlify.com/docs/mcp"
|
||
```
|
||
|
||
通过启动 Codex 会话并询问以下问题来测试连接：
|
||
|
||
```text
|
||
What tools do you have available?
|
||
```
|
||
|
||
Codex 应当将 Mintlify MCP 服务器列为可用工具。
|
||
|
||
查看 [Codex MCP 文档](https://developers.openai.com/codex/mcp)了解更多详情。
|
||
</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 搜索最相关的服务器。
|
||
* 断开未在主动使用的服务器，以减少潜在的上下文占用。
|