管理员 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 登录。完成认证后，Claude Code 会在后续调用中复用该会话。

使用 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 会在后续调用中复用该会话。详情请参见 Codex MCP 文档。

会话的工作方式

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

发现项目（可选）

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

检出 branch

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

读取、搜索和编辑

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

审查差异

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

保存

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

按需丢弃

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

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

直接编辑部署 branch

将部署 branch 传给 checkout，即可像在控制台编辑器中一样直接编辑它。例如 checkout { subdomain: "acme", branch: "main" }。Mintlify 会将会话绑定到部署 branch，而不是创建 admin-mcp/* branch。checkout 速度更快，并且不会创建拉取请求。在部署 branch 上，AI 工具以你的身份操作：

编辑对协作者实时可见。 在控制台中编辑部署 branch 的其他人会实时看到 AI 的更改。
save 只发布你的更改。 它会忽略 mode，将你的待处理更改直接提交到部署 branch，效果等同于在编辑器中点击 Publish。其他人未发布的更改保持待处理状态。你在控制台编辑器中未发布的编辑也会一并发布。
discard_session 只撤销你的更改。 它返回 discardedChanges，表示撤销的更改数量。其他人的更改和 branch 本身不受影响。
get_session_state 只列出你的更改。

Mintlify 按页面跟踪更改。如果你和其他人编辑了同一页面，save 会发布整个页面，discard_session 会撤销整个页面，包括其他人的编辑。在以下任一情况下，Mintlify 会改为从部署 branch 创建会话 branch。checkout 会返回一个说明原因的 note：

部署 branch 的保护规则要求拉取请求，或 Mintlify 无法检查你的 branch 保护规则。
部署 branch 的编辑在控制台编辑器中被锁定。
你的发布设置中关闭了 直接推送到你的部署 branch。
你使用客户端令牌或机器到机器令牌连接，而不是 OAuth 登录。这些令牌未关联到用户，因此没有”自己的”更改。

发布

控制台管理员 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。

图片

upload_image: 开始将本地图片文件上传到会话 branch。传入目标 path (例如 images/dashboard.png)、文件的 contentType 以及以字节为单位的确切 size。返回 uploadId、预签名的 uploadUrl，以及上传时需要发送的 headers。
finalize_image_upload: 将已上传的图片保存到会话 branch。传入 uploadId 和相同的 path。返回 src，你可以通过 edit_page 或 write_page 在 MDX 中引用它，或通过 update_config 在 docs.json 的 logo 或 favicon 字段中引用它。

调用 upload_image 后，AI 工具会使用 PUT 请求和返回的请求头将文件字节上传到 uploadUrl。例如：

curl -X PUT --upload-file ./dashboard.png -H 'Content-Type: image/png' '<uploadUrl>'

Mintlify 会在保存前检查上传文件的内容是否与其扩展名匹配。上传到已存在的 path 会替换该图片。Mintlify 仅接受用于 logo 和 favicon 的 SVG 文件，因此上传 SVG 时，请向两个工具都传入 purpose: "logo"。已保存的图片会显示在 get_session_state 中，并在你调用 save 时随会话的其他更改一起发布。

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> 父节点下。对于新页面，响应中会包含一个在控制台中打开该页面的 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。

如果 create_node、update_node、move_node 或 delete_node 调用使导航处于无效状态，响应中会包含描述该问题的 navigationErrors 字段。例如，将页面放在根级别并与 tab 并列时会返回 navigationErrors。Mintlify 可能会从已发布的导航中移除无效节点，因此请在调用 save 之前修复这些错误。

配置

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

项目管理

项目管理工具用于处理项目级操作，例如管理工作流、项目设置、自定义域名、Git 源、认证、成员、分析，以及私有页面的共享。这些工具不需要执行 checkout。每个工具都接收一个 subdomain，用于指定要操作的项目。组织级连接必须传入 subdomain。调用 list_deployments 查找它。读取工具还接受 subdomains，即最多 25 个项目的列表，并为每个项目返回结果或错误。大多数工具接收一个 request 对象，其 action 字段用于选择操作。例如：

{
  "subdomain": "acme",
  "request": { "action": "noindex", "noindex": true }
}

读取工具：

get_deployment_settings: 一次调用即可读取项目的仪表板设置、Git 源、自定义主机名状态和源检查。Slack 配置和代码片段需要选择性开启。
get_analytics_report: 读取预构建的分析报告，例如页面浏览量、热门页面、来源、反馈、助手对话或搜索质量。使用 request.report 选择报告。较大的结果通过 maxRows 和 rowOffset 分页。如需自定义查询，请使用 query_analytics。
get_workflows: 列出工作流、获取单个工作流，或分页查看其运行记录。
list_repos_and_prs: 列出已连接的仓库、某个仓库的拉取请求，或可在工作流中使用的集成。

写入工具：

update_deployment_settings: 更改一项仪表板设置，例如 noindex、base_path、name、disable_ai_chat、search_settings、privacy、custom_scripts 或某个附加功能。docs.json 设置请使用 update_config。
manage_custom_domain: 添加或移除自定义域名、配置其主机名，或重新触发主机名验证。
manage_git_source: 添加、更新、移除或重新排序项目构建所用的 Git 仓库，或设置基础源。
manage_access_auth: 配置或移除站点认证、添加或删除密码、配置终端用户认证，或切换当前启用的认证方式。
manage_workflow: 创建、更新、启用或禁用、删除或触发工作流。
manage_members_sharing: 列出或移除组织成员、更新其角色，或管理私有页面的授权和移动。

写入工具会在 state 下返回项目更新后的状态，因此 AI 工具无需再次调用即可确认更改。每个操作都会检查连接被授予的作用域以及你在仪表板中的角色。未获授权的操作会返回 insufficient_scope 等错误。

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

会话

list_deployments: 列出你的连接可以访问的项目，返回每个 {subdomain, name}。调用此项以了解要传递给 checkout 的 subdomain。
checkout: 将某个会话绑定到给定项目 subdomain 对应的 branch，或切换当前活动的项目会话。将部署 branch 作为 branch 传入即可直接编辑它。
list_branches: 列出某个项目仓库可用的 Git branch，可选用 query 进行筛选。返回 branch 名称、总数以及部署 branch。在 checkout 之前调用此项，可按名称附加到现有 branch。
get_session_state: 查看当前 branch、已编辑的文件和待处理的导航差异。在部署 branch 上，只列出你的更改。
diff: 列出会话与你的部署 branch 之间的所有更改。每个已更改的文件和 docs.json 条目都包含 authors 和 byYou。authors 列出该条目中包含其未发布编辑的成员。当该条目包含你自己的编辑时，byYou 为 true。在共享 branch 上，可使用 byYou 区分你的更改和同事的更改。
save: 打开拉取请求或提交到会话 branch。当项目配置为将 agent 更改推送到 main 且部署 branch 未受保护时，Mintlify 会自动合并该 PR。在部署 branch 上，只将你的待处理更改直接提交。
discard_session: 丢弃会话及其进行中的更改。在部署 branch 上，只撤销你的待处理更改。

示例提示词

连接管理员 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 工具对应的条目。撤销会在 30 秒内使该工具的访问令牌失效。此后工具调用会失败，工具在下次调用时必须完成新的 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

会话的工作方式

直接编辑部署 branch

发布

管理员 MCP 可以做什么

内容

图片

导航

配置

项目管理

会话

示例提示词

最佳实践

断开或撤销访问权限

​关于管理员 MCP

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

​前置条件

​连接到管理员 MCP

​会话的工作方式

​直接编辑部署 branch

​发布

​管理员 MCP 可以做什么

​内容

​图片

​导航

​配置

​项目管理

​会话

​示例提示词

​最佳实践

​断开或撤销访问权限

关于管理员 MCP

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

前置条件

连接到管理员 MCP

会话的工作方式

直接编辑部署 branch

发布

管理员 MCP 可以做什么

内容

图片

导航

配置

项目管理

会话

示例提示词

最佳实践

断开或撤销访问权限