> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型上下文协议

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

export const PreviewButton = ({children, href}) => {
  return <a href={href} className="text-sm font-medium text-white dark:!text-zinc-950 bg-zinc-900 hover:bg-zinc-700 dark:bg-zinc-100 hover:dark:bg-zinc-300 rounded-full px-3.5 py-1.5 not-prose">
        {children}
      </a>;
};

<div id="about-mcp-servers">
  ## 关于 MCP 服务器
</div>

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

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

<div id="accessing-your-mcp-server">
  ## 访问你的 MCP 服务器
</div>

<Note>
  只有公开文档才能生成 MCP 服务器。受终端用户认证保护的文档无法用于生成服务器。
</Note>

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

你可以在[控制台](https://dashboard.mintlify.com/products/mcp)中查看并复制你的 MCP 服务器 URL。

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

<div id="configuring-your-mcp-server">
  ## 配置 MCP 服务器
</div>

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

如果你订阅了 [Pro 或 Enterprise 方案](https://mintlify.com/pricing?ref=mcp)，可以将 OpenAPI规范 中的端点公开为 MCP 工具。

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

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

<ResponseField name="mcp" type="object">
  该端点的 MCP 配置。

  <Expandable title="MCP">
    <ResponseField name="enabled" type="boolean">
      是否将该端点公开为 MCP 工具。优先于文件级配置。
    </ResponseField>

    <ResponseField name="name" type="string">
      MCP 工具的名称。
    </ResponseField>

    <ResponseField name="description" type="string">
      MCP 工具的描述。
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="file-level-configuration">
  ### 文件级配置
</div>

在 OpenAPI规范 文件中默认为所有端点启用 MCP，并按需排除特定端点：

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

<div id="endpoint-level-configuration">
  ### 端点级配置
</div>

为特定端点启用 MCP：

```json
{
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "get-users",
            "description": "获取用户列表"
          },
          // ...
        }
      }
    },
    "/api/v1/delete": {
      "delete": {
        // 未设置 `x-mint: mcp`，因此该端点不会作为 MCP 工具对外提供
        // ...
      }
    }
  }
}
```

<div id="using-your-mcp-server">
  ## 使用你的 MCP 服务器
</div>

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

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

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

<Tabs>
  <Tab title="上下文菜单">
    在[上下文菜单](/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-connecting-to-the-mintlify-mcp-server">
  ### 示例：连接 Mintlify MCP 服务器
</div>

连接 Mintlify MCP 服务器以与 Mintlify API 交互并搜索我们的文档。这将为你在本地环境中如何使用 Mintlify 提供更准确的答案，并演示如何帮助你的用户连接到你的 MCP 服务器。

<Tabs>
  <Tab title="上下文菜单">
    在本页顶部，打开上下文菜单，选择 **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 服务器：

        * 名称：`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">Install in Cursor</PreviewButton>

    要将 Mintlify MCP 服务器连接到 Cursor，点击 **Install in 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">Install in VS Code</PreviewButton>

    要将 Mintlify MCP 服务器连接到 VS Code，点击 **Install in 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="authentication">
  ## 认证
</div>

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

如果用户要求其 AI 工具调用受保护的端点，工具会在当下向用户请求所需的身份验证凭据。

<div id="monitoring-your-mcp-server">
  ## 监控你的 MCP 服务器
</div>

你可以在控制台的 [MCP Server 页面](https://dashboard.mintlify.com/products/mcp) 的「Available tools」部分查看所有可用的 MCP 工具。

<Frame>
  <img src="https://mintcdn.com/mintlify-mintlify-add-hello-world-quickstart-48843/KAieJWDWb9msJsqT/images/mcp/mcp-server-page-light.png?fit=max&auto=format&n=KAieJWDWb9msJsqT&q=85&s=b2951db02e33abbb05c922faa7c9bcd3" alt="突出显示「Available tools」部分的 MCP 控制台" class="block dark:hidden" width="3024" height="1548" data-path="images/mcp/mcp-server-page-light.png" />

  <img src="https://mintcdn.com/mintlify-mintlify-add-hello-world-quickstart-48843/KAieJWDWb9msJsqT/images/mcp/mcp-server-page-dark.png?fit=max&auto=format&n=KAieJWDWb9msJsqT&q=85&s=75b9018915e26dbf4ddee8595fa94b8c" alt="突出显示「Available tools」部分的 MCP 控制台" class="hidden dark:block" width="3018" height="1540" data-path="images/mcp/mcp-server-page-dark.png" />
</Frame>

<div id="troubleshooting">
  ## 故障排查
</div>

<AccordionGroup>
  <Accordion title="MCP 服务器仅显示搜索工具">
    如果你的 MCP 服务器在已有 OpenAPI 规范的情况下只暴露了搜索工具：

    1. 验证你的 OpenAPI 规范是否有效且可访问。
    2. 确保已使用 `x-mint.mcp.enabled: true` 明确为相关端点启用 MCP。
    3. 查看部署日志中是否存在 OpenAPI 处理错误。

    如果 OpenAPI 处理失败，服务器会仅保留搜索工具以维持基本可用性。
  </Accordion>

  <Accordion title="认证问题">
    如果用户反馈认证相关问题：

    1. 检查你的 OpenAPI 规范是否包含正确的 `securitySchemes` 定义。
    2. 确认已启用的端点能与指定的认证方式正常工作。
  </Accordion>

  <Accordion title="工具描述缺失或不清晰">
    如果 AI 工具未能有效使用你的 API 端点：

    1. 为端点补充详尽的 `summary` 和 `description` 字段。
    2. 确保参数名称和描述清晰易懂。
    3. 使用 MCP 控制台核对端点作为工具时的呈现效果。
  </Accordion>
</AccordionGroup>