> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol

> 让用户通过他们常用的 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>

Model Context Protocol（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 工具，请在文件级或端点级的 `x-mint` 扩展中使用 `mcp` 对象。例如，Mintlify 的 MCP 服务器包含用于创建 AI 助手会话、获取状态更新和触发更新的工具。

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 theme={null}
{
  "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>

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

```json theme={null}
{
  "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="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 theme={null}
        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 theme={null}
        {
          "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 theme={null}
        {
          "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="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 theme={null}
    claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp
    ```

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

    ```bash theme={null}
    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 theme={null}
        {
          "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 theme={null}
    {
      "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` 中定义的认证要求。任何 key 都由工具直接处理，不会由 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/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/mcp/mcp-server-page-light.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=8e8149e1692e4a212f49ff96bfdb7d95" 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/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/mcp/mcp-server-page-dark.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=ddb49e7c8de96f257d1e6df1518e0299" 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>