管理员 Model Context Protocol (MCP) 服务器

让 Claude 和 Cursor 等 AI 工具获得对你的 Mintlify 内容和控制台的写入权限，从而编辑页面、更新设置并提交 PR。

关于管理员 MCP

管理员 MCP 服务器赋予 AI 工具对你的 Mintlify 内容和设置的写入权限。可使用它来更新内容并访问你的控制台。借助管理员 MCP，你可以使用你常用的 AI 工具来编辑页面、调整导航结构、更新 docs.json、提交拉取请求、修改设置、创建工作流等等。

将任意 MCP 客户端 (例如 Claude、Claude Code 或 Cursor) 连接到管理员 MCP 服务器，即可使用与编写代码相同的工具协同处理你的 Mintlify 内容和设置。使用管理员 MCP 服务器时，所有更改都会发生在某个 branch 上，并需要通过拉取请求合并。如果你的组织有多个部署，单个管理员 MCP 连接即可访问所有这些部署并在它们之间切换。

管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的同事。仅从受信任的 AI 工具连接它，并在合并前审查每一个拉取请求。

管理员 MCP 与搜索 MCP 的区别

	管理员 MCP	搜索 MCP
受众	你的团队	你的终端用户
权限	读取、编辑、调整结构、保存、创建工作流、管理设置	读取并搜索已发布的页面
端点	由 Mintlify 托管，仅限于你的项目	位于你的站点域名上的 /mcp
输出	内容编辑、导航更改、拉取请求、工作流运行	搜索结果和页面内容

前置条件

在连接管理员 MCP 之前，请确认以下事项：

• Mintlify 账户：你需要一个 Mintlify 账户，并具有对你想要编辑的项目的访问权限。OAuth 会话会继承你的控制台权限，因此仅限管理员的操作 (例如对受保护设置执行 update_config) 需要该项目上的管理员角色。
• Git 提供方访问权限：为该项目安装的 Mintlify GitHub App 或 GitLab 连接必须对部署 branch 所在的仓库具有写入权限。save 会通过与常规部署相同的集成打开 PR。
• MCP 客户端：一款支持 MCP 的 AI 工具，例如 Claude、Claude Code、Cursor 或 Codex。

连接到管理员 MCP

你必须通过 Mintlify 账户完成交互式 OAuth 登录才能连接到管理员 MCP。AI 工具会将该登录会话兑换为一个会话令牌，其作用域为一个或多个部署，具体取决于你授予访问权限的方式。限定到特定部署的连接只能对这些部署执行 checkout，而组织范围的连接可以对你组织中的任意部署执行 checkout。

Claude

1. Add the admin MCP as a custom connector

   1. 前往 Claude 设置中的 Connectors 页面。
   2. 点击 Add custom connector。
   3. 添加连接器
      • 名称：Admin MCP
      • URL：https://mcp.mintlify.com
   4. 点击 Add 并完成 OAuth 登录。
2. Use the MCP in a chat

   点击附件按钮 (加号图标)，然后选择你的管理员 MCP 服务器。Claude 现在可以在回答你的提示时调用 Mintlify 管理员 MCP 工具。

Claude Code

使用 Claude Code CLI 添加管理员 MCP 服务器：

claude mcp add --transport http mintlify https://mcp.mintlify.com

首次使用时，Claude Code 会打开一个浏览器窗口以完成 OAuth 登录。完成认证后，后续调用会复用该会话。

Cursor

1. 使用 Command + Shift + P (Windows 上为 Ctrl + Shift + P) 打开命令面板。
2. 搜索 Open MCP settings 并点击 Add custom MCP。
3. 在 mcp.json 中添加管理员 MCP：

{
  "mcpServers": {
    "mintlify": {
      "url": "https://mcp.mintlify.com"
    }
  }
}

4. 重新加载 Cursor，并在出现提示时完成 OAuth 登录。

Codex

在 ~/.codex/config.toml 中的 Codex CLI 配置里添加管理员 MCP 服务器：

[mcp_servers.mintlify]
url = "https://mcp.mintlify.com"

首次使用时，Codex 会打开一个浏览器窗口以完成 OAuth 登录。完成认证后，后续调用会复用该会话。

详情请参见 Codex MCP 文档。

会话的工作方式

每个管理员 MCP 会话都绑定到单个 Git branch。流程如下：

1. Discover deployments (optional)

   如果你的连接可以访问多个部署，请调用 list_deployments 以查看可用于 checkout 的 subdomain 值。如果你的连接仅覆盖单个部署，请跳过此步骤。

2. Check out a branch

   第一次必需的调用是 checkout {subdomain}。它会从该部署的部署 branch 基础上创建一个全新的 mintlify-mcp/<slug>-<sha> branch (或附加到你指定的现有 branch)，并返回一个 editorUrl，你可以打开它在控制台编辑器中实时跟进。

   如果你需要发现或筛选某个部署仓库中现有的 branch，请在 checkout 之前调用 list_branches。

3. Read, search, and edit

   AI 使用 search、read、list_nodes、edit_page、write_page、create_node 和 update_config 等工具进行更改。所有编辑都会实时缓冲在会话 branch 上——目前还不会影响你的部署 branch。

4. Review the diff

   随时调用 diff 查看与 main 相比发生了哪些更改。在控制台中打开 editorUrl，可以看到相同更改的渲染效果。

5. Save

   调用 save 将 branch 推送到 Git。使用 mode: "pr" (默认值) 创建拉取请求，或使用 mode: "commit" 直接推送到现有的 PR branch。

6. Discard if needed

   调用 discard_session 丢弃所有会话内更改并释放该 branch。

如果你的连接可以访问多个部署，每个已 checkout 的部署都会同时在内存中保留其各自的会话和 branch。

使用不同的 subdomain 或 branch 再次调用 checkout 会切换当前活动的会话，而不会丢弃其他会话。若要放弃进行中的草稿而不仅仅是切换离开它，请调用 discard_session。

管理员 MCP 可以做什么

内容

• read — 获取会话 branch 上任意页面的完整 MDX。
• search — 在所有页面中查找匹配子字符串或正则表达式的行。
• edit_page — 对页面进行有针对性的编辑。
• write_page — 覆盖页面的完整 MDX 内容。

导航

• list_nodes — 遍历导航树，可使用可选筛选条件。按 parentId 筛选 (使用 recursive: true 包含所有后代)、按一个或多个节点类型筛选，或按任意分区范围筛选：language、version、tab、dropdown、anchor、product 或 item。结果通过不透明的 cursor 分页。
• create_node — 添加新的页面、组、tab、anchor、版本、语言、产品或 dropdown。
• update_node — 就地更新节点属性 (重命名组、更改图标、设置默认版本)。
• move_node — 移动节点，包括重命名页面的路径。
• delete_node — 从导航中移除节点。

配置

• update_config — 修改 docs.json (主题、导航根节点、集成、SEO 设置)。

会话

• list_deployments — 列出你的连接可以访问的部署，返回每个 {subdomain, name}。调用此项以了解要传递给 checkout 的 subdomain。
• checkout — 将某个会话绑定到给定部署 subdomain 对应的 branch，或切换当前活动的部署会话。
• list_branches — 列出某个部署项目可用的 Git branch，可选用 query 进行筛选。返回 branch 名称、总数以及部署 branch。在 checkout 之前调用此项，可按名称附加到现有 branch。
• get_session_state — 查看当前 branch、已编辑的文件和待处理的导航差异。
• diff — 列出会话与 main 之间的所有更改。
• save — 打开拉取请求或提交到会话 branch。
• discard_session — 丢弃会话及其进行中的更改。

示例提示词

连接管理员 MCP 后，你可以使用自然语言提示词来驱动它。例如：

• “检出一个名为 add-billing-faq 的 branch，并在 FAQ 组下创建一个名为 ‘Billing’ 的新页面。为这个 Linear 工单中的五个问题草拟答案。”
• “找出每一个提到已废弃的 legacy_token 字段的页面，并将示例更新为使用 api_key。保存为一个标题为 ‘docs: replace legacy_token references’ 的 PR。”
• “重新组织 API 参考：将 webhooks 页面移入名为 ‘Webhooks’ 的新组，并更新图标以与该部分其他内容保持一致。”

最佳实践

打开编辑器 URL

每次 checkout 都会返回一个 editorUrl。在单独的标签页中打开它，这样你就可以在提示时实时观察 AI 的更改在控制台编辑器中渲染。

审查每一个 PR

管理员 MCP 强大到足以在一次会话中重写数百个页面。在合并之前，请阅读 PR 差异并大致浏览渲染预览。不要对大量更改做盲目通过。

使用 slug 作为 branch 名称

向 checkout 传入 slug (例如 add-quickstart)，使自动生成的 branch 易于阅读。如果不传入，branch 名称会基于会话令牌生成，在你的仓库中很难辨识。

保持会话聚焦

让每个会话专注于一项更改。更小的会话能生成更易审查的拉取请求，并能节省代理的上下文窗口。使用 discard_session 后再次 checkout 以切换到无关的工作。

会话在 Mintlify 端会持有一个内存中的 branch。如果你在没有保存或丢弃的情况下放弃会话，该 branch 会一直保留到你下一次 checkout 覆盖它为止。请避免在你的仓库中留下陈旧的 mintlify-mcp/* branch，并定期清理它们。

断开或撤销访问权限

当你不再希望某个 AI 工具编辑你的项目，或想要强制重新完成 OAuth 登录时，请断开管理员 MCP。

• 撤销 OAuth 授权：在你的 Mintlify 控制台中，前往 Settings → Security & access → Connected apps，然后撤销你所连接的 AI 工具对应的条目。撤销会立即使所有活动的会话令牌失效，进行中的工具调用会失败，工具在下次调用时必须完成新的 OAuth 登录。
• 在客户端中移除连接器：
  • Claude：Settings → Connectors，然后移除管理员 MCP 条目。
  • Claude Code：claude mcp remove mintlify。
  • Cursor：从 mcp.json 中删除 mintlify 条目并重新加载。
  • Codex：从 ~/.codex/config.toml 中删除 [mcp_servers.mintlify] 代码块。

撤销 OAuth 授权不会影响 MCP 已经打开的拉取请求。如果你想撤销待处理的更改，请在你的 Git 提供方中关闭或还原这些 PR。