在发现端点中宣告外部托管的 MCP 服务器

Mintlify 为每个站点托管一个搜索 MCP 服务器，并通过搜索 MCP 服务器中描述的 /.well-known/mcp、/.well-known/mcp.json、/.well-known/mcp/server-card.json 和 /.well-known/mcp/server-cards.json 端点进行宣告。这些端点会自动生成，且只列出 Mintlify 为你的站点托管的 MCP 服务器（公共的 /mcp 端点，以及在使用认证时的 /authed/mcp）。docs.json 中没有可用来在这些响应中添加第二个外部托管 MCP 服务器的字段。 Mintlify 通过代理 Link 头部宣告的 /.well-known/api-catalog 端点也是如此：该目录列出从 docs.json 中提取的 OpenAPI 文档，而不是 MCP 服务器。如果你在 Mintlify 之外运行自己的 MCP 服务器，并希望它在文档域名上与内置服务器一同可被发现，请使用下面的一种方案。

方案 1：通过反向代理提供你自己的发现文档

如果你的文档已经通过位于自有域名上的反向代理提供，则该域名下的 /.well-known/* 路径由你掌控。在代理中拦截 MCP 发现路径，并返回一个同时列出两个服务器的 JSON 文档，而不是将请求转发给 Mintlify。使用与 Mintlify 为 /.well-known/mcp 返回的相同结构，以便现有 MCP 客户端继续工作：

{
  "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": "external",
      "url": "https://mcp.your-domain.com",
      "transport": "http",
      "authentication": "oauth2"
    }
  ]
}

一个 nginx 片段示例：为 MCP 发现路径提供静态文件，而不是转发给 Mintlify：

location = /.well-known/mcp {
    default_type application/json;
    alias /etc/nginx/well-known/mcp.json;
}

location = /.well-known/mcp.json {
    default_type application/json;
    alias /etc/nginx/well-known/mcp.json;
}

注意事项：

使用 Content-Type: application/json 提供内容，并禁用缓存（Cache-Control: no-store），以便代理立即获取更新。
覆盖发现路径会隐藏 Mintlify 的内置响应。请在你所提供的文件中包含 Mintlify 托管的 /mcp（以及在适用时的 /authed/mcp）条目，这样读取发现文档的客户端仍然可以找到内置搜索服务器。
如果你还覆盖了 /.well-known/mcp/server-card.json 或 /.well-known/mcp/server-cards.json，请遵循 server-card 格式，以便从这些端点预填元数据的工具继续工作。

方案 2：直接公布外部 MCP URL

如果你不使用反向代理，或者不想维护一个静态发现文件，可以像公布内置服务器一样，将外部 MCP 服务器的 URL 公布给用户。参见使用你的 MCP 服务器中适用于内置服务器、也同样适用于第二个 URL 的模式：

在文档中添加一页，列出两个 MCP 服务器的 URL，并说明如何在 Claude、Cursor、VS Code 或其他客户端中分别连接。
为内置服务器添加上下文菜单条目，方便用户一键复制 URL 或安装命令。上下文菜单选项仅涵盖 Mintlify 托管的 MCP 服务器，因此请在旁边手动记录外部 URL。

支持多个 MCP 服务器的客户端可以分别指向内置的 /mcp 端点和外部 URL；无需列在同一个发现文档中即可使用。

Mintlify 当前不支持的行为

将外部 MCP 服务器 URL 加入 docs.json 中某个字段，让 Mintlify 在 /.well-known/mcp* 响应中一并返回。
在 /.well-known/api-catalog 下列出 MCP 服务器。该端点仅面向 OpenAPI 文档。

如果上述任一功能能解决你的场景，请联系 support@mintlify.com，说明你的用例。

​方案 1：通过反向代理提供你自己的发现文档

​方案 2：直接公布外部 MCP URL

​Mintlify 当前不支持的行为

方案 1：通过反向代理提供你自己的发现文档

方案 2：直接公布外部 MCP URL

Mintlify 当前不支持的行为