跳转到主要内容

​
关于 MCP 服务器

Model Context Protocol（MCP，模型上下文协议）是一个开放协议，用于在 AI 应用与外部服务（例如文档）之间建立标准化连接。Mintlify 会基于你的文档和 OpenAPI 规范生成一个 MCP 服务器，为更广泛的 AI 生态系统做好准备，让任何 MCP 客户端（例如 Claude、Cursor、Goose 等）都可以连接到你的文档和 API。 你的 MCP 服务器会向 AI 应用提供工具，以便搜索你的文档并与你的 API 交互。

​
MCP 服务器的工作方式

当 MCP 服务器连接到某个 AI 工具时，LLM 可以在生成回复时决定使用你的文档和 API 工具。
  • 在生成回复的过程中，LLM 可以主动搜索你的文档或调用你的 API 端点，而不仅仅是在被显式要求时才这样做。
  • LLM 会根据对话的上下文以及你的文档和 API 的相关性来决定何时使用这些工具。
  • 每次调用工具都发生在生成过程中，使 LLM 能够在回复中融入来自你的文档和 API 的实时信息。
例如，如果用户提出一个编程问题，而 LLM 判断你的 API 文档是相关的，它就可以搜索你的 API 文档，并在回复中包含这些信息，而无需用户明确要求使用你的文档。

​
访问你的 MCP 服务器

仅能为公开文档生成 MCP 服务器。需要终端用户认证的文档无法用于生成服务器。
Mintlify 会为你的文档自动生成一个 MCP 服务器，并将其托管在你的文档 URL 的 /mcp 路径下。例如，Mintlify 的 MCP 服务器位于 https://mintlify.com/docs/mcp。 你可以在控制台查看并复制你的 MCP 服务器 URL。 /mcp 路径保留用于托管 MCP 服务器，不能用于其他导航元素。

​
配置你的 MCP 服务器

所有 MCP 服务器默认都包含 search 工具，它允许用户在其他工具中查询你文档中的信息。 如果你订阅了 Pro 或 Custom 方案，可以将 OpenAPI 规范中的端点暴露为 MCP 工具。 要将端点暴露为 MCP 工具，请在文件级或端点级的 x-mint 扩展中使用 mcp 对象。比如，Mintlify 的 MCP 服务器包含用于创建 AI 助手会话、获取状态更新以及触发更新的工具。 MCP 服务器采用安全优先的策略，API 端点默认不对外暴露。你必须显式启用端点，才能将其作为 MCP 工具使用。仅暴露那些可通过 AI 工具公开访问且安全的端点。
​
mcp
object
该端点的 MCP 配置。

​
文件级配置

在一个 OpenAPI 规范文件中，默认为所有端点启用 MCP，并可选择性地排除部分端点： 
{
  "openapi": "3.1.0",
  "x-mint": {
    "mcp": {
      "enabled": true
    }
  },
  // ...
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": false // 禁用此端点的 MCP
          }
        },
        // ...
      }
    }
  }
}

​
端点级配置

为特定端点启用 Model Context Protocol（MCP）： 
{
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "get-users",
            "description": "获取用户列表"
          },
          // ...
        }
      }
    },
    "/api/v1/delete": {
      "delete": {
        // 没有 `x-mint: mcp`，所以此端点不会作为 MCP 工具公开
        // ...
      }
    }
  }
}

​
使用你的 MCP 服务器

你的用户需要将你的 MCP 服务器连接到他们常用的 AI 工具。
  1. 将你的 MCP 服务器 URL 公开可访问。
  2. 让用户复制你的 MCP 服务器 URL 并添加到他们的工具中。
  3. 用户即可通过其工具访问你的文档和 API 端点。
以下是一些你可以帮助用户连接到你的 MCP 服务器的方法：
  • Contextual menu
  • Claude
  • Claude Code
  • Cursor
  • VS Code
在上下文菜单中为用户添加选项，使其可从文档任意页面连接到你的 MCP 服务器。
选项标识符说明
复制 MCP 服务器 URLmcp将你的 MCP 服务器 URL 复制到用户的剪贴板。
连接到 Cursorcursor在 Cursor 中安装你的 MCP 服务器。
连接到 VS Codevscode在 VS Code 中安装你的 MCP 服务器。

​
示例：连接 Mintlify MCP 服务器

连接 Mintlify MCP 服务器以与 Mintlify API 交互并搜索我们的文档。这样你就能在本地环境中更精准地了解如何使用 Mintlify，同时也演示了如何帮助你的用户连接到你的 MCP 服务器。
  • Contextual menu
  • Claude
  • Claude Code
  • Cursor
  • VS Code
在本页顶部打开上下文菜单，选择 Connect to Cursor 或 Connect to VS Code，即可将 Mintlify MCP 服务器连接到你选择的 IDE。

​
认证

当你为 MCP 启用某个 API 端点时，服务器会包含在 OpenAPI 的 securitySchemes 和 securityRequirement 中定义的认证要求。任何 key 都由工具直接处理，不会由 Mintlify 存储或处理。 如果用户让其 AI 工具调用受保护的端点，工具会在该时刻向用户请求所需的认证凭据。

​
监控你的 MCP 服务器

你可以在控制台的 MCP 服务器页面 的 Available tools 部分查看所有可用的 MCP 工具。
控制台中突出显示“Available tools”部分的 MCP

​
故障排查

如果你的 MCP 服务器在已有 OpenAPI 规范的情况下仍只显示搜索工具：
  1. 检查 OpenAPI 规范是否有效且可访问。
  2. 确认已通过 x-mint.mcp.enabled: true 明确为相关端点启用 MCP。
  3. 查看部署日志中是否有 OpenAPI 处理错误。
如果 OpenAPI 处理失败，服务器会仅保留搜索工具以确保基本功能可用。
如果用户反馈认证相关问题：
  1. 检查 OpenAPI 规范是否包含正确的 securitySchemes 定义。
  2. 确认已启用的端点能与指定的认证方式正常配合。
如果 AI 工具未能有效利用你的 API 端点：
  1. 为端点补充详细的 summary 和 description 字段。
  2. 确保参数名称和说明清晰易懂。
  3. 使用 MCP 控制台查看端点作为工具时的呈现效果。