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

关于管理员 MCP

管理员 MCP 服务器赋予 AI 工具对你的 Mintlify 内容和设置的写入权限。可使用它来更新内容并访问你的控制台。借助管理员 MCP，你可以使用你常用的 AI 工具来编辑页面、调整导航结构、更新 docs.json、提交拉取请求、修改设置、创建工作流等等。将任意 MCP 客户端 (例如 Claude、Claude Code、ChatGPT 或 Cursor) 连接到管理员 MCP 服务器，即可使用与编写代码相同的工具协同处理你的 Mintlify 内容和设置。内容编辑会发生在某个 branch 上，并在你调用 save 时通过拉取请求或提交交付。项目管理更改 (例如工作流和设置更新) 会立即应用到线上项目。如果你的组织有多个项目，单个管理员 MCP 连接即可访问所有这些项目并在它们之间切换。

管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的同事。仅从受信任的 AI 工具连接它，在合并前审查每一个拉取请求，并注意项目管理更改会在没有拉取请求的情况下立即生效。

管理员 MCP 是由 Mintlify 托管的服务，地址为 https://mcp.mintlify.com。每个客户端都连接到同一个端点，并使用你的 Mintlify 账户进行身份认证。

管理员 MCP 与其他 Mintlify MCP 服务器的区别

	管理员 MCP	搜索 MCP	Index MCP
受众	你的团队	你的终端用户	所有开发者和代理
权限	读取、编辑、调整结构、保存、创建工作流、管理设置	读取并搜索某个站点的已发布页面	读取并搜索所有 Mintlify 站点
端点	`https://mcp.mintlify.com`	位于你的站点域名上的 `/mcp`	`https://index.mintlify.com`
输出	内容编辑、导航更改、拉取请求、工作流运行	你站点的搜索结果和页面内容	所有 Mintlify 站点的搜索结果和页面内容

请参阅 Mintlify Index MCP 参考，了解其工具输入和速率限制。

前置条件

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

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

连接到管理员 MCP

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

Claude
Claude Code
ChatGPT
Cursor
Codex

Add the admin MCP as a custom connector

前往 Claude 设置中的 Connectors 页面。
点击 Add custom connector。
添加连接器
- 名称：Admin MCP
- URL：https://mcp.mintlify.com
点击 Add 并完成 OAuth 登录。

Use the MCP in a chat

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

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

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

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

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

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

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

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

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

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

会话的工作方式

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

Discover projects (optional)

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

Check out a branch

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

Read, search, and edit

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

Review the diff

随时调用 diff 查看与你的部署 branch 相比发生了哪些更改。在控制台中打开 editorUrl，可以看到相同更改的渲染效果。当 create_node 添加页面时，会返回一个直接打开该页面的 editorUrl。

Save

调用 save 将 branch 推送到 Git。mode: "auto"（默认值）会创建一个拉取请求；如果该项目的 agent review 设置为 push-to-main 且部署 branch 未受保护，则会立即将其合并（响应中包含 merged: true）。使用 mode: "pr" 始终创建拉取请求并保持其打开以供审查，或使用 mode: "commit" 直接推送到现有的 PR branch，而不打开新的 PR。当 save 创建或更新拉取请求时，响应中会包含一个 editorUrl，用于打开该 branch 上第一个新建或更新的页面。如果更改只涉及配置，该链接会打开 branch。立即合并的保存不会返回 editorUrl。

Discard if needed

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

如果你的连接可以访问多个项目，每个已 checkout 的项目都会同时在内存中保留其各自的会话和 branch。使用不同的 subdomain 或 branch 再次调用 checkout 会切换当前活动的会话，而不会丢弃其他会话。若要放弃进行中的草稿而不仅仅是切换离开它，请调用 discard_session。

发布

控制台管理员 MCP 设置页面上的发布部分用于控制 save 在 mode: "auto" 下运行时的行为。开启 直接推送到你的部署 branch，Mintlify 会将更改直接推送到你的部署 branch。关闭它，save 将改为打开一个拉取请求。此开关与 Slack 和控制台代理共享相同的 agentReviewProcess 设置，因此在这里所做的任何更改都会同样应用于那些流程。以下三种情况下该开关会被禁用：

你的部署 branch 需要拉取请求。 如果 branch 保护规则或必需的审批阻止了直接推送，那么无论此设置如何，MCP 更改都会始终打开拉取请求。
Mintlify 托管你的项目。 对于由 Mintlify 托管的站点，MCP 更改会始终直接推送，除非 branch 保护仍然要求拉取请求。
你不是管理员。 更改此设置需要项目的管理员角色。编辑者和查看者会看到该开关被禁用，并显示权限横幅。

你也可以通过向 save 传递显式的 mode 来按调用覆盖该设置："pr" 始终打开拉取请求，"commit" 会推送到现有的 PR branch 而不打开新的 PR。

管理员 MCP 可以做什么

内容

read: 获取会话 branch 上任意页面的完整 MDX。可以传入页面路径（如 /quickstart），也可以传入编辑器 URL 中的页面 ID（~/ 之后的部分），让 AI 工具直接通过编辑器链接打开页面。要读取私有页面，请传入通过 list_nodes 加 visibility: "private" 获取的 private-page-<uuid> 节点 ID。私有读取无需 checkout，但需要 OAuth 会话。管理员 MCP 会拒绝使用客户端令牌和机器到机器令牌访问私有页面。
search: 在所有页面中查找匹配子字符串或正则表达式的行。
edit_page: 对页面进行有针对性的编辑。要编辑私有页面，请将其 private-page-<uuid> 节点 ID 作为 path 传入。私有编辑需要在该页面拥有 editor 或更高角色的 OAuth 会话，且无需 checkout。
write_page: 覆盖页面的完整 MDX 内容。可接受 private-page-<uuid> 节点 ID 以覆盖私有页面，其 OAuth 与角色要求与 edit_page 相同。要创建新的私有页面，请使用 create_node。

list_nodes: 遍历导航树，可使用可选筛选条件。按 parentId 筛选 (使用 recursive: true 包含所有后代)、按一个或多个节点类型筛选，或按任意分区范围筛选：language、version、tab、dropdown、anchor、product 或 item。结果通过不透明的 cursor 分页。传入 visibility: "private" 可以列出 OAuth 用户有权访问的私有页面和文件夹，而不是 branch 的导航树。私有列表无需 checkout，会忽略其他筛选条件，并返回每个节点的 role。
create_node: 添加新的页面、组、tab、anchor、版本、语言、产品或 dropdown。传入 visibility: "private" 并配合 data.type: "page" 或 data.type: "group"，可在调用者的私有树中创建私有页面或私有文件夹。调用者会成为该节点的 manager。私有创建需要 OAuth 会话，无需 checkout，并会将节点放在私有根目录下，或放在现有的 private-folder-<uuid> 父节点下。对于会话 branch 上的新页面，响应中会包含一个在控制台编辑器中打开该页面的 editorUrl。
update_node: 就地更新节点属性 (重命名组、更改图标、设置默认版本)。可接受 private-page-<uuid> 或 private-folder-<uuid> 节点 ID，用于重命名私有页面或私有文件夹，或更改其图标或 tag。私有更新需要具有 editor 或更高角色的 OAuth 会话，且无需 checkout。
move_node: 移动节点，包括重命名页面的路径。
delete_node: 从导航中移除节点。可接受 private-page-<uuid> 或 private-folder-<uuid> 节点 ID，用于从调用者的私有树中删除私有页面或私有文件夹。私有删除需要在该节点上具有 manager 角色的 OAuth 会话，且无需 checkout。

配置

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

项目管理

代码模式 (code mode) 用于处理没有专用工具的项目级操作，例如管理工作流、项目设置、成员、账单、集成、分析，以及私有页面的共享。代码模式的工具不需要执行 checkout。

search_code_operations: 搜索代码模式可用的项目管理方法。每个结果都包含该方法的完整输入 schema。
execute_code: 针对项目管理方法运行一段 TypeScript 脚本。连接被授予的作用域会控制每个方法的访问权限，任何未被授予的方法都会返回授权错误。

代码模式的写入会立即应用到线上项目。它们不会创建 branch，也不会打开拉取请求。在提示 AI 工具更新工作流、设置、成员、账单或集成之前，请先确认预期的更改。

会话

list_deployments: 列出你的连接可以访问的项目，返回每个 {subdomain, name}。调用此项以了解要传递给 checkout 的 subdomain。
checkout: 将某个会话绑定到给定项目 subdomain 对应的 branch，或切换当前活动的项目会话。
list_branches: 列出某个项目仓库可用的 Git branch，可选用 query 进行筛选。返回 branch 名称、总数以及部署 branch。在 checkout 之前调用此项，可按名称附加到现有 branch。
get_session_state: 查看当前 branch、已编辑的文件和待处理的导航差异。
diff: 列出会话与你的部署 branch 之间的所有更改。
save: 打开拉取请求或提交到会话 branch。当项目配置为将 agent 更改推送到 main 且部署 branch 未受保护时，会自动合并该 PR。
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 会返回 branch 的 editorUrl。create_node 和 save 会返回已更改页面的 editorUrl。在单独的标签页中打开这些链接，这样你就可以在提示时实时观察 AI 的更改在控制台编辑器中渲染。

审查每一个 PR

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

使用 slug 作为 branch 名称

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

保持会话聚焦

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

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

断开或撤销访问权限

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

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

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

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

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

关于管理员 MCP

管理员 MCP 与其他 Mintlify MCP 服务器的区别

前置条件

连接到管理员 MCP

会话的工作方式

发布

管理员 MCP 可以做什么

内容

导航

配置

项目管理

会话

示例提示词

最佳实践

断开或撤销访问权限

​关于管理员 MCP

​管理员 MCP 与其他 Mintlify MCP 服务器的区别

​前置条件

​连接到管理员 MCP

​会话的工作方式

​发布

​管理员 MCP 可以做什么

​内容

​导航

​配置

​项目管理

​会话

​示例提示词

​最佳实践

​断开或撤销访问权限

关于管理员 MCP

管理员 MCP 与其他 Mintlify MCP 服务器的区别

前置条件

连接到管理员 MCP

会话的工作方式

发布

管理员 MCP 可以做什么

内容

导航

配置

项目管理

会话

示例提示词

最佳实践

断开或撤销访问权限