跳转到主要内容

​
关于 MCP 服务器

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

​
访问你的 MCP 服务器

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

​
配置 MCP 服务器

所有 MCP 服务器默认包含 search 工具，允许用户在其他工具中查询你文档中的信息。 如果你订阅了 Pro 或 Enterprise 方案，可以将 OpenAPI规范 中的端点公开为 MCP 工具。 要将端点公开为 MCP 工具，请在文件级或端点级的 Mintlify OpenAPI扩展 x-mint 中使用 mcp 对象。例如，Mintlify MCP 服务器包含用于创建文档助手会话、获取状态更新以及触发更新的工具。 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
          }
        },
        // ...
      }
    }
  }
}

​
端点级配置

为特定端点启用 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 服务器的方式：
  • 上下文菜单
  • 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 服务器。
  • 上下文菜单
  • Claude
  • Claude Code
  • Cursor
  • VS Code
在本页顶部，打开上下文菜单，选择 Connect to Cursor 或 Connect to VS Code，将 Mintlify MCP 服务器连接到你所用的 IDE。

​
认证

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

​
监控你的 MCP 服务器

你可以在控制台的 MCP Server 页面 的「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 控制台核对端点作为工具时的呈现效果。