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

管理员 MCP 与搜索 MCP 的区别

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

连接到管理员 MCP

你必须通过 Mintlify 账户完成交互式 OAuth 登录才能连接到管理员 MCP。AI 工具会将该登录会话兑换为限定到单个项目的会话令牌。

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 登录。

会话的工作方式

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

1. Check out a branch

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

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

2. Read, search, and edit

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

3. Review the diff

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

4. Save

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

5. Discard if needed

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

在活动会话期间再次调用 checkout 会将会话切换到新的 branch。可借此放弃进行中的草稿，并在不结束对话的情况下重新开始。

管理员 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 设置)。

会话

• checkout — 将会话绑定到某个 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，并定期清理它们。