跳转到主要内容

​
关于管理员 MCP

管理员 MCP 服务器赋予 AI 工具对你的 Mintlify 内容和设置的写入权限。可使用它来更新内容并访问你的控制台。借助管理员 MCP，你可以使用你常用的 AI 工具来编辑页面、调整导航结构、更新 docs.json、提交拉取请求、修改设置、创建自动化等等。 将任意 MCP 客户端 (例如 Claude、Claude Code、ChatGPT 或 Cursor) 连接到管理员 MCP 服务器。连接后，你可以使用与编写代码相同的工具协同处理你的 Mintlify 内容和设置。每次内容工具调用都会指定其操作的 branch。对部署 branch 的编辑会作为未发布的更改落在该 branch 上，对其他任何 branch 的编辑则通过拉取请求进行。你调用 publish 或合并拉取请求时，这些编辑才会交付。项目管理更改 (例如自动化和设置更新) 会立即应用到线上项目。如果你的组织有多个项目，单个管理员 MCP 连接即可访问所有这些项目并在它们之间切换。
管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的工具。仅从受信任的 AI 工具连接它，在合并前审查每一个拉取请求，并注意项目管理更改会在没有拉取请求的情况下立即生效。
管理员 MCP 是由 Mintlify 托管的服务，地址为 https://mcp.mintlify.com。每个客户端都连接到同一个端点，并使用你的 Mintlify 账户进行身份认证。

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

​
前置条件

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

​
连接到管理员 MCP

你必须通过 Mintlify 账户完成交互式 OAuth 登录才能连接到管理员 MCP。AI 工具会将该登录会话兑换为一个会话令牌，其作用域为一个或多个项目，具体取决于你授予访问权限的方式。限定到特定项目的连接只能访问这些项目。组织范围的连接可以访问你组织中的任意项目。 你可以在控制台中将工具连接到管理员 MCP，或按照以下步骤为你偏好的工具完成连接。
要从终端配置 Claude Code、Codex 或 Cursor，请运行 mint agent setup。该命令会将管理员 MCP 添加到每个代理的配置中，并安装 Mintlify 技能。你仍需在每个代理中完成 OAuth 登录。
1

添加 Mintlify 连接器

  1. 在 Claude 连接器目录中打开 Mintlify 连接器。
  2. 点击 Connect 并完成 OAuth 登录。
如需改为将其添加为自定义连接器，请前往 Claude 设置中的 Connectors 页面，点击 Add custom connector，然后输入 URL https://mcp.mintlify.com。
2

在聊天中使用 MCP

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

​
将连接限制为搜索和读取工具

如果要连接的 AI 工具只需要在你的内容中查找信息，请在添加管理员 MCP 时发送 x-mintlify-toolset: knowledge 请求头。之后，该连接只会列出以下工具：search、read、read_comments、read_page_history、list_nodes、list_branches 和 list_deployments。该连接上的 AI 工具无法编辑内容、发布或更改设置。 管理员 MCP 还会为 AI 工具提供更简短的说明，专注于搜索和读取页面。 例如，使用 Claude Code 时：

​
编辑的工作方式

每个内容工具都接受 branch 参数。会更改内容的工具（例如 edit_page、create_node、update_config、publish 和 discard）必须传入该参数。读取类工具（例如 read、search、read_page_history、list_nodes、status 和 diff）在省略该参数时默认使用你的部署 branch。管理员 MCP 不会在调用之间记住 branch，因此 AI 工具每次都会传入 branch。针对私有页面的请求不需要 branch。管理员 MCP 只能访问 Base 中的私有页面。在文档项目中，私有页面请求会返回 private_pages_unavailable。 流程如下：
1

发现项目（可选）

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

读取、搜索和编辑

AI 使用 search、read、list_nodes、edit_page、write_page、create_node 和 update_config 等工具进行更改。在组织范围的连接上，请传入 subdomain 来选择项目。将部署 branch 作为 branch 传入即可直接编辑它。编辑会作为未发布的更改落在该 branch 上。参见直接编辑部署 branch。如果你的项目要求拉取请求，Mintlify 会拒绝该编辑并返回说明原因的消息，且不会做任何更改。此时请调用 create_branch，并将返回的 branchName 作为 branch 传入。参见在 branch 上工作。
3

审查差异

随时调用 diff 查看某个 branch 与你的部署 branch 相比发生了哪些更改。调用 status 可获取已编辑文件、已更改的 docs.json 键和导航更改的摘要。省略 branch 时，两者都会报告你的部署 branch。在控制台中打开 editorUrl，可以看到相同更改的渲染效果。当 create_node 添加页面时，会返回一个直接打开该页面的 editorUrl。
4

发布

调用 publish 并传入 branch 和 title 以发布你的编辑。管理员 MCP 会告知 AI 工具，仅在你要求其发布、上线或合并时才调用 publish，因此在你提出要求之前，你的编辑会保持未发布状态。在部署 branch 上，publish 会提交你自己的待处理更改。在 branch 上，publish 会提交所有待处理内容并返回该 branch 的拉取请求，如果还没有拉取请求则会创建一个。在没有新内容可提交时再次调用，会返回现有的拉取请求。如果既没有可提交的内容也没有拉取请求，publish 会返回 no_pending_changes。除非你传入 merge: true，否则 publish 不会合并拉取请求。传入 merge: true 时，publish 还会将拉取请求合并到你的部署 branch，并返回 merged: true。只有在 Mintlify 接受直接编辑你的部署 branch 时，才允许合并。参见直接编辑部署 branch。否则，publish 会返回 merge_not_allowed 及原因，并保持拉取请求为打开状态以供审核。只有在你希望更改跳过审核时，才让 AI 工具执行合并。响应中包含一个 editorUrl，用于打开第一个新建或更新的页面。如果更改只涉及配置，该链接会打开 branch。旧版客户端仍可传入 mode，但 publish 会忽略它。
5

检查部署

当 publish 提交到你的部署 branch 时（无论是直接提交还是通过合并拉取请求），响应中会包含一个 commitSha 和一个 deployment 对象。在部署完成之前，你的更改不会在站点上线。使用 commitSha 调用 deployment_status 以检查进度。AI 工具大约每 30 秒检查一次，直到 live 为 true；如果状态为 failed、not_live 或 skipped，则停止并报告 message。
6

按需丢弃

调用 discard 并传入 branch 以放弃你的编辑。它会删除哪些内容取决于该 branch。参见直接编辑部署 branch和在 branch 上工作。
每次调用都会指定其项目和 branch，因此你可以在同一个对话中处理多个项目或 branch，而无需在它们之间切换。

​
直接编辑部署 branch

当没有任何条件要求拉取请求时，将部署 branch 作为 branch 传入，管理员 MCP 就会像你在控制台编辑器中一样编辑它。你无需调用 create_branch，也不会创建拉取请求。 在部署 branch 上，AI 工具以你的身份操作：
  • 编辑对协作者实时可见。 在控制台中编辑部署 branch 的其他人会实时看到 AI 的更改。
  • publish 只发布你的更改。 它将你的待处理更改直接提交到部署 branch，效果等同于在编辑器中点击 Publish。其他人未发布的更改保持待处理状态。你在控制台编辑器中未发布的编辑也会一并发布。
  • discard 只撤销你的更改。 它返回 discardedChanges，表示撤销的更改数量。其他人的更改和 branch 本身不受影响。
  • status 只列出你的更改。
Base 没有文档站点，因此没有发布步骤。当 list_deployments 返回 projectType: "workspace" 时，该项目即为 Base，Mintlify 会自动将编辑提交到部署 branch，包括上传的图片。 Mintlify 按页面跟踪更改。如果你和其他人编辑了同一页面，publish 会发布整个页面，discard 会撤销整个页面，包括其他人的编辑。 在以下任一情况下，Mintlify 会拒绝对部署 branch 的编辑，且不会做任何更改：
  • 你的发布设置中关闭了 直接推送到你的部署 branch。
  • 部署 branch 的保护规则要求拉取请求，或 Mintlify 无法检查你的 branch 保护规则。
  • 部署 branch 的编辑在控制台编辑器中被锁定。
  • 你使用客户端令牌或机器到机器令牌连接，而不是 OAuth 登录。这些令牌未关联到用户，因此没有”自己的”更改。
Mintlify 会在每次编辑时检查这些条件，并将你的 branch 保护规则缓存最多 30 秒。当对部署 branch 的编辑被拒绝时，评论工具仍可在其上使用。如果你编辑部署 branch 之后它开始要求拉取请求，publish 会返回 branch_protected，你的更改保持待处理状态。请打开控制台编辑器，将这些更改移到新的 branch。

​
启用自动发布的项目

如果你的项目启用了自动发布，管理员 MCP 不会为该项目使用 branch。请将你的部署 branch 作为 branch 传入。Mintlify 会自动将你的编辑提交到部署 branch。 在这些项目中，Mintlify 会拒绝 create_branch 以及针对任何其他 branch 的调用，且不会做任何更改。如果你的连接仅涵盖该项目，管理员 MCP 不会列出 create_branch 或 list_branches。 在启用自动发布的项目中，直接推送到你的部署 branch 和 branch 保护规则不会阻止对部署 branch 的编辑。当部署 branch 的编辑在控制台编辑器中被锁定，或者你使用客户端令牌或机器到机器令牌连接时，Mintlify 会拒绝编辑。

​
要求审阅的项目

如果你的项目要求发布前审阅，只有管理员可以对部署 branch 使用 publish。对于其他任何人，在部署 branch 上调用 publish 会返回 review_required，更改保持待处理状态。 在其他 branch 上，publish 会提交你的更改并打开拉取请求。管理员可以使用 merge: true 将拉取请求合并到部署 branch。在审阅者于控制台编辑器中批准了 branch 上的所有更改（包括其 Site changes）后，发布者也可以合并。对于其他任何人，合并会返回 review_required，拉取请求保持打开状态，因此请改为在编辑器中请求审阅。 要发布你的更改，请让 AI 工具请求审阅。AI 工具会使用你更改的页面和你指定的审阅者调用 request_review。审阅者批准更改后，管理员或发布者会在控制台编辑器中或通过 publish_review_request 发布这些更改。相关工具请参见审阅请求。

​
在 branch 上工作

当你的项目要求拉取请求，或者你本身就想要一个拉取请求时，请调用 create_branch 并传入 title。Mintlify 会从部署 branch 创建一个新的 branch，按照与控制台编辑器相同的方式将其命名为 <your-name>/<title-slug>，并基于你已发布的内容进行初始化。拉取请求会以此标题打开。例如 create_branch { subdomain: "acme", title: "Add tips page" }。 create_branch 返回 branchName、起始的 baseBranch 和 baseSha、一个 note，以及一个可在控制台编辑器中实时跟进的 editorUrl。在之后的每次调用中，将 branchName 作为 branch 传入。 要在现有 branch 上工作，请将其名称作为 branch 传入。调用 list_branches 可发现项目仓库中的 branch。Mintlify 会拒绝针对不存在的 branch 的调用。 在 branch 上，Mintlify 会在最后一次更改约 15 秒后自动提交你的编辑，包括页面内容、导航更改和 docs.json 更新。首次提交会打开一个针对部署 branch 的拉取请求。如果启用了默认创建草稿 pull request，拉取请求会以草稿形式打开。在有人合并该拉取请求之前，任何更改都不会进入你的部署 branch。 在部署 branch 以外的 branch 上，discard 会删除该 branch 并关闭其拉取请求，即使该 branch 已有提交。这与在控制台编辑器中删除 branch 的效果相同。discard 只会删除你在 Mintlify 中创建的 branch。对于其他 branch，它会拒绝操作且不做任何更改。

​
发布

控制台侧边栏中 MCP → Configure 页面上的 发布 部分用于控制管理员 MCP 是否可以在不使用拉取请求的情况下编辑你的部署 branch。开启 直接推送到你的部署 branch，AI 工具即可直接编辑并发布到你的部署 branch。关闭它，MCP 编辑将需要 create_branch 和拉取请求。 此开关与 Slack 和控制台代理共享相同的 agentReviewProcess 设置，因此在这里所做的任何更改都会同样应用于那些流程。 以下三种情况下该开关会被禁用：
  • 你的部署 branch 需要拉取请求。 如果 branch 保护规则或必需的审批阻止了直接推送，那么无论此设置如何，MCP 更改都会始终通过拉取请求进行。
  • Mintlify 托管你的项目。 对于由 Mintlify 托管的站点，MCP 更改会始终直接推送，除非 branch 保护仍然要求拉取请求。
  • 你不是管理员。 更改此设置需要项目的管理员角色。编辑者和查看者会看到该开关被禁用，并显示权限横幅。

​
重定向 URI

Claude、ChatGPT 和 Cursor 等常用 MCP 客户端始终可以完成 OAuth 登录。要允许其他客户端连接，请在 MCP → Configure 的 Redirect URIs 部分添加它们的重定向域名。在 Allowed domains 字段中输入域名或自定义 scheme（例如 myapp://callback），然后点击 Add domain。 允许的域名同时适用于管理员 MCP 和你的 Search MCP 服务器。

​
凭据

凭据让 AI 应用和网关无需交互式登录即可连接到管理员 MCP。在用户无法完成 OAuth 登录的环境中使用凭据。
  1. 在控制台侧边栏中，点击 MCP，然后点击 Credentials。
  2. 点击 Create credential。
  3. 复制密钥。控制台只会显示一次该密钥。
凭据可以读取内容，但不能更改内容。编辑、评论、创建 branch、发布或丢弃内容的工具以及 read_inbox 需要 OAuth 登录，使用凭据调用时会返回 user_principal_required。 要撤销凭据，请点击其旁边的删除图标。

​
管理员 MCP 可以做什么

​
内容

  • read: 获取 branch 上任意页面的完整 MDX；省略 branch 时，则获取部署 branch 上的页面。可以传入页面路径（例如 guides/setup），或编辑器 URL 的最后一段，即页面 ID，其前面可能带有标题。使用编辑器 URL 中的页面 ID 时，请将该 URL 中的 branch 作为 branch 传入。响应中包含 filePath，你可以将其作为 path 传给 edit_page 和 write_page；响应中还包含所返回内容的 version。传入 forEdit: true 可读取实时页面，而不是其已保存的副本。在使用 write_page 覆盖页面之前，请使用 forEdit: true。要读取私有页面，请传入通过 list_nodes 加 visibility: "private" 获取的 private-page-<uuid> 节点 ID。私有读取无需 branch，但需要 OAuth 会话。管理员 MCP 会拒绝使用客户端令牌和机器到机器令牌访问私有页面。
  • search: 按语义和精确措辞搜索 branch 上的页面；省略时搜索部署 branch。将问题、主题、名称或精确短语作为 query 传入。默认情况下，search 会以 results 的形式优先返回最相关的页面。每个结果包含页面的 path 和 title，以及包含匹配行的 snippets。当 search 对排名第一的结果有把握时，该结果还会包含页面的完整 content，最多 16 KB。其后的结果会包含其最佳匹配周围的 section。传入 limit 可返回最多 20 个页面（默认 6 个）。如需列出包含某个短语的所有页面（例如在重命名之前），请传入 mode: "all"（默认 limit 为 100，最大 500）。传入 regex: true 会将 query 视为正则表达式，并始终使用 mode: "all"。
  • edit_page: 对页面进行有针对性的编辑。path 的传入形式与 read 相同。传入 oldString 和 newString 进行单次替换，或传入最多包含 100 个替换的 edits 列表，在一次调用中修改页面的多个部分。Mintlify 按顺序应用这些编辑，每个编辑都基于上一个编辑的结果。如果任一编辑失败，则所有编辑都不会应用。与 write_page 一样，edit_page 会针对编辑新增且被编辑器丢弃的标记返回 notRendered。它不会报告页面上原本已有的标记。要编辑私有页面，请将其 private-page-<uuid> 节点 ID 作为 path 传入。私有编辑需要在该页面拥有 editor 或更高角色的 OAuth 会话，且无需 branch。
  • write_page: 覆盖页面的完整 MDX 内容。path 的传入形式与 read 相同。覆盖页面之前，请先调用带 forEdit: true 的 read，并将返回的 version 作为 baseVersion 传给 write_page。如果页面在那次读取之后发生了变化，Mintlify 会拒绝写入，不做任何更改，并返回 page_changed。请重新读取页面并再次应用你的更改。如果在有内容的页面上省略 baseVersion，write_page 会返回 base_version_required。仅包含 frontmatter 的页面不需要 baseVersion。也可接受 private-page-<uuid> 节点 ID 以覆盖私有页面，其 OAuth 与角色要求与 edit_page 相同。要创建新的私有页面，请使用 create_node。如果内容包含会被 Mintlify 编辑器丢弃的标记，例如 <script> 标签、<style> 块、onClick 等事件处理器或 JavaScript 表达式，响应中会包含 notRendered 字段。每个条目会列出被丢弃的 element、其所在的 line、编辑器丢弃它的原因 why，以及应改用的 instead 方案，例如 Tailwind 类、使用字面量值的内联 style={{}} 对象，或手风琴和标签页等 Mintlify 组件。
  • read_page_history: 列出页面在 branch 上保存的版本历史；省略时使用你的部署 branch。path 的传入形式与 read 相同，包括 private-page-<uuid> 节点 ID。返回按从新到旧排序的 versions 以及 nextCursor。每个版本包含 versionId、createdAt 和 authors，每位作者都有 name 以及取值为 user、git 或 system 的 type。传入 limit 可每次调用返回 1 到 50 个版本（默认 20 个），将 nextCursor 作为 cursor 传回即可列出更早的版本。传入 versionId 可获取该版本的完整 MDX，结果位于 content 中。该工具为只读。要恢复早期版本，请先对该页面调用带 forEdit: true 的 read，然后将早期版本的 content 传给 write_page，并将那次读取返回的 version 作为 baseVersion 传入。如果该版本包含页面上已不存在的内联数据，write_page 无法恢复这些数据。请改为在编辑器中通过版本历史恢复该版本。错误包括 page_not_found、version_not_found 和 invalid_cursor。

​
内联数据

页面可以将图片和其他文件嵌入为 base64 data URL。为了让响应保持精简，read、search、diff、read_page_history 和 read_comments 会将每个长度达到 1,000 个字符及以上的 base64 内容替换为占位符，例如 [elided 48210 chars #1234567890]。 将内容传回时，请保持这些占位符不变。edit_page、write_page、create_node 和 suggest_edit 会使用目标页面当前内容中的原始数据替换每个占位符。 如果某个占位符与目标页面上的数据不匹配，Mintlify 会拒绝写入，不做任何更改，并返回 inline_data_unresolved。请仅从同一页面的 read 结果中复制占位符。如果 Mintlify 无法读取页面来恢复占位符，它会返回 inline_data_source_unreadable，且不做任何更改。请重试该调用。

​
上传

  • upload_file: 开始上传本地文件。传入目标 path、文件的 contentType 以及以字节为单位的确切 size。返回 uploadId、预签名的 uploadUrl，以及上传时需要发送的 headers。
  • finalize_file_upload: 将已上传的图片保存到 branch。传入 uploadId 和相同的 path。返回 src，你可以通过 edit_page 或 write_page 在 MDX 中引用它，或通过 update_config 在 docs.json 的 logo 或 favicon 字段中引用它。
调用 upload_file 后，AI 工具会使用 PUT 请求和返回的请求头将文件字节上传到 uploadUrl。例如：
要添加图片，请将图片 path（例如 images/dashboard.png）和 branch 传给 upload_file。上传完成后，调用 finalize_file_upload。Mintlify 会在保存前检查上传文件的内容是否与其扩展名匹配。上传到已存在的 path 会替换该图片。只有 logo 和 favicon 上传可以使用 SVG 文件：上传此类文件时，请向两个工具都传入 purpose: "logo"。页面图片不能是 SVG。已保存的图片会显示在 status 中，并在你调用 publish 时随你的其他编辑一起发布。 要基于本地 Markdown 文件写入页面，请传入 .md 或 .mdx 的 path，并将 contentType 设置为 text/markdown 或 text/plain。页面上传不需要 branch，也不需要 finalize_file_upload。上传完成后，将 uploadId 代替 content 传给 write_page，或作为 data.uploadId 传给 create_node。这样可以避免在工具调用中重新发送大型页面的完整内容。 请在 10 分钟内使用 uploadId。每个 uploadId 只能使用一次，且只能在同一项目中、由创建它的同一用户或客户端使用。Mintlify 会在写入后删除已上传的文件。重复使用或已过期的 uploadId 会返回 upload_not_found。

​
评论

处理团队在控制台编辑器中留下的评论和建议。
  • read_comments: 列出页面上未解决的评论和建议线程，按从旧到新排序。path 接受与 read 相同的格式。每个线程包含 threadId、type（comment 或 suggestion）、线程锚定的 quotedText、建议的 suggestedText，以及 comments（每条包含 author、content 和 createdAt）。如果锚定的文本已不在页面上，线程会包含 anchorRemoved: true，quotedText 显示原始引用。读取 branch 上的线程；省略时读取部署 branch 上的线程。
  • add_comment: 在页面上发起新的评论线程，不会更改页面内容。可用于给团队留下反馈，而不是直接编辑。path 接受与 read 相同的格式，content 为评论内容，quotedText 为要锚定的最短且唯一的可见文本片段，且须位于同一段落或标题内。请使用渲染后的文字，而不是 Markdown 或 MDX 语法。例如，引用 custom domain，而不是 [custom domain](/path)。返回新的 threadId。如果页面上没有该文本，会返回 no_match 错误。如果匹配到多处，会返回 not_unique 错误，此时请引用更长的片段。
  • suggest_edit: 在页面上提出带修订标记的建议，而不是直接编辑。原文会以删除线形式保留在页面上，替换内容显示在其旁边。在有人于控制台编辑器中接受或拒绝该建议之前，页面内容不会改变。path 接受与 read 相同的格式，并传入 oldString 和 newString。oldString 为要替换的最短且唯一的可见文本片段，且须位于同一段落或标题内。请使用渲染后的文字，而不是 Markdown 或 MDX 语法。传入空的 newString 可建议删除。可传入可选的 comment 来说明该修改的价值。Mintlify 会将其作为代理在建议线程中的回复发布。旧的 note 参数仍可使用，作为 comment 的已弃用别名。返回新的 threadId，以及裁剪到实际变更片段的 originalText 和 suggestedText。如果相同的建议已处于打开状态，响应会包含 alreadyExists: true 和现有的 threadId。no_match 和 not_unique 错误与 add_comment 相同。两个字符串相同时返回 no_change 错误，文本与另一条打开的建议重叠时返回 conflicting_annotation 错误。
  • reply_to_comment: 通过 threadId 和 content 回复线程。传入 resolve: true 可同时解决该线程。Mintlify 会以 agent 身份代表授权用户发布回复，回复会实时显示在控制台编辑器中。
  • resolve_comment: 解决线程而不回复。
  • read_inbox: 列出你在某个项目上的控制台收件箱，按最新活动排序。收件箱包括评论和提及、建议的编辑、审阅请求以及与你共享的私有页面和文件夹。默认情况下，read_inbox 返回未处理的项目。将 state 设为 open、done 或 all，将 section 设为 comment、suggestion、invitation、request 或 all（默认）。request 分区包括审阅请求和邀请。传入 filter 可将评论限定为 mentions 或 on-my-page（你拥有的页面），将建议限定为来自 people 或 agent 的建议，或将 request 分区限定为 requests 或 invites。除非 section 为 all，否则筛选条件必须与 section 匹配。传入 ISO 8601 日期时间格式的 dateFrom 和 dateTo，可按最新活动时间限定项目。传入 limit 可指定每次调用返回 1 到 50 个项目（默认 20），并将 nextCursor 作为 cursor 传回以列出更早的项目。每个项目都包含其 category、state、latestActivity 和 target。当 target.thread 存在、未解决且不在私有页面上时，在其 branch 上使用其 filePath 调用 read_comments，并使用 reply_to_comment 回复。restricted 项目不包含线程详情。read_inbox 为只读操作，绝不会将项目标记为已读或已完成。错误包括 invalid_filter、invalid_date_range 和 invalid_cursor。
add_comment、suggest_edit、reply_to_comment 和 resolve_comment 需要 OAuth 会话和 branch。它们处理该 branch 上的线程，即使对部署 branch 的编辑要求拉取请求，它们也可以在部署 branch 上使用。你可以回复建议线程，但必须在编辑器中接受或拒绝建议。管理员 MCP 不支持私有页面上的评论。read_inbox 同样需要 OAuth 会话，并且只返回该项目所属组织中活跃成员的收件箱。
  • list_nodes: 遍历 branch 的导航树（省略时为部署 branch 的导航树），可使用可选筛选条件。按 parentId 筛选 (使用 recursive: true 包含所有后代)、按一个或多个节点类型筛选，或按任意分区范围筛选：language、version、tab、dropdown、anchor、product 或 item。上传的文件和文件夹（file 和 file_directory 节点）仅在你将其加入类型筛选条件时才会出现。每个节点都会返回其 id、type、text 和 parent，并在适用时返回 path、pageId 和 hidden。将页面的 path 传给 read 即可获取其内容和 frontmatter。结果通过不透明的 cursor 分页。传入 visibility: "private" 可以列出 OAuth 用户有权访问的私有页面和文件夹，而不是 branch 的导航树。私有列表会忽略 branch 和其他筛选条件，并返回每个节点的 role。
  • create_node: 添加新的页面、组、tab、anchor、版本、语言、产品或 dropdown。传入 visibility: "private" 并配合 data.type: "page" 或 data.type: "group"，可在调用者的私有树中创建私有页面或私有文件夹。调用者会成为该节点的 manager。私有创建需要 OAuth 会话，无需 branch，并会将节点放在私有根目录下，或放在现有的 private-folder-<uuid> 父节点下。对于新页面，响应中会包含一个在控制台中打开该页面的 editorUrl。如果 branch 上的 path 处已存在页面，create_node 会将新内容写入该页面，而不会失败。即使你传入了不同的父节点，该页面也会保留其在导航中的位置，并且响应中会包含 updated: true。如果 Mintlify 将新页面添加到导航中但无法保存其内容，create_node 会返回 PAGE_SEED_FAILED。使用相同的 path 再次调用 create_node 即可写入内容。
  • update_node: 就地更新节点属性 (重命名组、更改图标、设置默认版本)。可接受 private-page-<uuid> 或 private-folder-<uuid> 节点 ID，用于重命名私有页面或私有文件夹，或更改其图标或 tag。私有更新需要具有 editor 或更高角色的 OAuth 会话，且无需 branch。
  • move_node: 移动节点，包括重命名页面的路径。
  • delete_node: 从导航中移除节点。可接受 private-page-<uuid> 或 private-folder-<uuid> 节点 ID，用于从调用者的私有树中删除私有页面或私有文件夹。私有删除需要在该节点上具有 manager 角色的 OAuth 会话，且无需 branch。
如果 create_node、update_node、move_node 或 delete_node 调用使导航处于无效状态，响应中会包含描述该问题的 navigationErrors 字段。例如，将页面放在根级别并与 tab 并列时会返回 navigationErrors。Mintlify 可能会从已发布的导航中移除无效节点，因此请在调用 publish 之前修复这些错误。

​
配置

  • update_config: 更改 docs.json 的顶层设置，例如主题、颜色、logo、导航栏、页脚、重定向、集成和 SEO。它无法更改 navigation，请改用导航工具。Mintlify 会整体拒绝无效的配置。

​
Mintlify skill

  • read_skill: 读取 Mintlify 的文档编写指南，内容涵盖页面、组件、widget、导航和 docs.json。它与 agent 使用的 Mintlify skill 相同。不传 path 调用时，会返回 skill 的索引 SKILL.md 以及其参考文件的 files 列表。从该列表中选取一个文件作为 path 传入（例如 reference/widgets.md）即可读取该文件。该工具为只读，不需要 subdomain 或 branch。如果文件不存在，则返回 skill_file_not_found 以及 files 列表。
索引响应还包含一个 skills 列表，列出你的组织和你本人已启用的 agent skills，每项都包含 name、description 和 path。传入某个 skill 的 path（例如 org/release-notes/SKILL.md）即可读取其说明。响应会在 files 中列出该 skill 的参考文件，你可以将其中任意一个作为 path 传入。个人 skill 的路径以 me/ 开头，且仅在 OAuth 会话中显示。 管理员 MCP 会指示 AI 工具在编写、重构页面或设置页面样式之前先调用 read_skill，并遵循任何描述与当前任务相符的组织或个人 skill。

​
项目管理

项目管理工具用于处理项目级操作，例如管理自动化、项目设置、自定义域名、Git 源、认证、成员、分析，以及私有页面的共享。这些工具作用于线上项目，而不是某个 branch。 每个工具都接收一个 subdomain，用于指定要操作的项目。组织级连接必须传入 subdomain。调用 list_deployments 查找它。读取工具还接受 subdomains，即最多 25 个项目的列表，并为每个项目返回结果或错误。大多数工具接收一个 request 对象，其 action 字段用于选择操作。例如：
读取工具：
  • get_deployment_settings: 一次调用即可读取项目的仪表板设置、Git 源、自定义主机名状态和源检查。Slack 配置和代码片段需要选择性开启。
  • get_analytics_report: 读取预构建的分析报告，例如页面浏览量、热门页面、来源、反馈、助手对话或搜索质量。使用 request.report 选择报告。较大的结果通过 maxRows 和 rowOffset 分页。如需自定义查询，请使用 query_analytics。
  • get_analytics_schema: 读取 query_analytics 接受的表、事件和 SQL 规则。AI 工具会在编写查询前调用一次。
  • query_analytics: 对你站点的分析数据运行一条只读 SELECT 查询，例如页面浏览量、搜索、助手、反馈，以及 Agent 和人类流量。结果已限定在该项目范围内。如果项目未启用分析查询，这两个分析查询工具都会返回 not_enabled 错误。
  • 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: 配置或移除站点认证、添加或删除密码、配置终端用户认证，或切换当前启用的认证方式。切换时仅会保留 JWT 配置。如果当前启用的配置使用其他任何类型，切换会以 409 错误失败，且不会更改你的站点。要更改为其他类型，请直接配置新的认证方式。当某个操作启用站点认证时（包括从终端用户认证切换过来），Mintlify 会删除既没有组织登录也没有密码保护的现有预览。将 previewDeployments 设置为 delete_unauthenticated（默认）、delete_all 或 keep，以选择如何处理现有预览。
  • manage_workflow: 创建、更新、启用或禁用、删除或触发自动化。
  • manage_workflow_prs: 合并或关闭由自动化运行创建的拉取请求。要合并 AI 工具编辑过的 branch 的拉取请求，请改用带 merge: true 的 publish。
  • manage_members_sharing: 列出、邀请或移除组织成员、更新其角色，或在 Base 中管理私有页面的授权和移动。单次调用最多可邀请 250 人，并会跳过已是成员或已有待处理邀请的人员。
写入工具会在 state 下返回项目更新后的状态，因此 AI 工具无需再次调用即可确认更改。每个操作都会检查连接被授予的作用域以及你在仪表板中的角色。未获授权的操作会返回 insufficient_scope 等错误。
项目管理写入会立即应用到线上项目。它们不会创建 branch，也不会打开拉取请求。在提示 AI 工具更新自动化、设置、域名、认证或成员之前，请先确认预期的更改。

​
审阅请求

只有当你的项目要求发布前审阅时，才会出现这些工具。它们作用于你的部署 branch，不接受 branch 参数。
  • list_review_requests: 列出部署 branch 上未完成的审阅请求。每个请求都包含其 requester、reviewers 及其 state，以及其 pages。每个页面都有 path、title 和 approval，值为 approved、pending，或在页面于批准后发生更改时为 stale。不属于某个页面的更改（例如导航和站点设置）会显示为一个标题为 Site changes 的项目。
  • request_review: 请审阅者批准你的待处理更改。以与 read 相同的形式传入最多 100 个 pages，并传入 reviewers，每位审阅者以 email 或 role 表示。role: "admin" 会请求所有管理员。role: "editor" 会请求所有发布者；如果你的组织没有发布者角色，则请求所有编辑者。如果你有不属于某个页面的待处理更改，且没有其他未完成的请求包含这些更改，Mintlify 会将 Site changes 项目添加到请求中。Mintlify 只会请求除你之外、可以批准的活跃成员。每位审阅者都会收到一封电子邮件和一条收件箱项目。错误包括页面没有可审阅内容时的 no_pending_changes，以及没有可批准的人员与 reviewers 匹配时的 no_reviewers。
  • withdraw_review_request: 按 requestId 撤回你发起的审阅请求。传入 reviewer 邮箱可只移除该审阅者。移除最后一位审阅者会撤回该请求。页面会保留其待处理更改。
  • approve_review_request: 按 requestId 批准他人的审阅请求，相当于在编辑器中点击 Approve。管理员 MCP 会告知 AI 工具，只有在你要求批准该特定请求时才可批准，并且要先与你确认请求者和页面。对于你自己的请求返回 own_request，对于你创建的 branch 返回 own_branch，如果你的角色无法批准则返回 not_reviewer，如果更改在 AI 工具读取后被编辑过则返回 changed。
  • publish_review_request: 按 requestId 发布已批准的审阅请求，并传入用作提交信息的 title，相当于在编辑器中发布同事已获批准的更改。管理员和发布者可以发布。管理员 MCP 会告知 AI 工具，只有在你要求发布该特定请求时才可发布。在每个页面的当前版本都获得批准之前返回 not_approved；当另一个未完成的请求占用了此请求所需的导航更改时返回 navigation_held；如果你的角色无法发布则返回 not_allowed；对于 branch 上的请求返回 merge_required，该请求会在其拉取请求合并时发布。使用 deployment_status 跟踪返回的 deployment。

​
branch 与发布

  • list_deployments: 列出你的连接可以访问的项目，返回每个 {subdomain, name, projectType}。projectType 为 site 表示文档站点，为 workspace 表示 Base。调用此项以了解要传递的 subdomain。
  • create_branch: 从部署 branch 创建一个新的 branch，并传入同时用作其拉取请求标题的 title。返回要作为 branch 传入的 branchName。参见在 branch 上工作。直接编辑部署 branch 时不需要它。
  • list_branches: 列出某个项目仓库可用的 Git branch，可选用 query 进行筛选。返回 branch 名称、总数以及部署 branch。其中任意一个都可以作为 branch 传入。
  • status: 列出 branch（省略时为部署 branch）上已编辑的文件、已更改的 docs.json 键和待处理的导航差异。在部署 branch 上，只列出你的更改。
  • diff: 列出 branch 与你的部署 branch 之间的所有更改。每个已更改的文件和 docs.json 条目都包含 authors 和 byYou。authors 列出该条目中包含其未发布编辑的成员。当该条目包含你自己的编辑时，byYou 为 true。在共享 branch 上，可使用 byYou 区分你的更改和同事的更改。
  • publish: 在部署 branch 上，只将你的待处理更改直接提交。如果你的项目要求审阅且你不是管理员，在部署 branch 上或传入 merge: true 时会返回 review_required。参见要求审阅的项目。在 branch 上，提交待处理更改并返回该 branch 的拉取请求，必要时创建一个。在允许编辑部署 branch 时，传入 merge: true 可同时合并该拉取请求。当更改进入部署 branch 时，还会返回一个 deployment 状态，可通过 deployment_status 跟踪。
  • deployment_status: 检查已发布的更改是否已在你的文档站点上线。传入 publish 返回的 commitSha，或省略它以检查最新一次部署。返回 state（pending、queued、building、live、not_live、failed 或 skipped 之一），以及 live 和一条用于告知你的 message。not_live 表示站点仍在提供较早的版本，例如部署被回滚，或你的部署固定在较早的版本上。
  • discard: 放弃 branch 上的编辑。在部署 branch 上，只撤销你的待处理更改。在你创建的其他 branch 上，删除该 branch 并关闭其拉取请求。

​
示例提示词

连接管理员 MCP 后，你可以使用自然语言提示词来驱动它。例如：
  • “创建一个标题为 ‘Add billing FAQ’ 的 branch，并在 FAQ 组下创建一个名为 ‘Billing’ 的新页面。为这个 Linear 工单中的五个问题草拟答案。”
  • “找出每一个提到已废弃的 legacy_token 字段的页面，并将示例更新为使用 api_key。发布为一个标题为 ‘docs: replace legacy_token references’ 的 PR。”
  • “重新组织 API 参考：将 webhooks 页面移入名为 ‘Webhooks’ 的新组，并更新图标以与该部分其他内容保持一致。”
  • “读取快速入门页面上未解决的评论，完成所要求的编辑，并回复每个线程，处理完毕后将其解决。”

​
最佳实践

create_branch 会返回 branch 的 editorUrl。create_node 和 publish 会返回已更改页面的 editorUrl。在单独的标签页中打开这些链接，这样你就可以在提示时实时观察 AI 的更改在控制台编辑器中渲染。
管理员 MCP 强大到足以在一次会话中重写数百个页面。在合并之前，请阅读 PR 差异并大致浏览渲染预览。不要对大量更改做盲目通过。
让每个 branch 专注于一项更改。更小的 branch 能生成更易审查的拉取请求，并能节省代理的上下文窗口。再次调用 create_branch 以开始无关的工作。
如果你放弃了通过 create_branch 创建的 branch 而没有丢弃它，该 branch 及其拉取请求会保留在你的仓库中。调用 discard 可删除不再需要的 branch，你也可以关闭其拉取请求。

​
断开或撤销访问权限

当你不再希望某个 AI 工具编辑你的项目，或想要强制重新完成 OAuth 登录时，请断开管理员 MCP。
  • 撤销 OAuth 授权：在你的 Mintlify 控制台中，前往 MCP 设置，然后撤销你所连接的 AI 工具对应的条目。撤销会在 30 秒内使该工具的访问令牌失效。此后工具调用会失败，工具在下次调用时必须完成新的 OAuth 登录。
  • 删除凭据：要撤销使用凭据的 AI 应用或网关的访问权限，请前往 MCP 设置中的 Credentials 页面并将其删除。
  • 在客户端中移除连接器：管理员 MCP 条目的 URL 为 https://mcp.mintlify.com。其名称取决于你添加它的方式，例如 mintlify-admin 或 mintlify。
    • Claude：Settings → Connectors，然后移除 Mintlify 条目。
    • Claude Code：运行 claude mcp list 查找该条目的名称，然后运行 claude mcp remove <name>。
    • ChatGPT：Settings → Connectors，然后移除 Mintlify 条目。
    • Cursor：卸载 Mintlify 插件，或从 mcp.json 中删除该条目并重新加载。
    • Codex：从 ~/.codex/config.toml 或项目中的 .codex/config.toml 中删除该条目的 [mcp_servers.<name>] 代码块。
撤销 OAuth 授权不会影响 MCP 已经打开的拉取请求。若要撤销待处理的更改，请在你的 Git 提供方中关闭或还原这些 PR。

​
故障排除

你的 AI 工具正在使用 Mintlify 更新登录系统之前保存的连接。请重新安装 Mintlify 连接器：先从你的 AI 工具中将其移除，然后重新添加。各工具的具体步骤请参阅断开或撤销访问权限。
退出控制台，重新登录，然后再次连接你的 AI 工具。这会替换在登录系统更新之前开始的控制台会话。
你的 AI 工具中有多个指向 https://mcp.mintlify.com 的条目。当你通过多种方式连接管理员 MCP 时就可能出现这种情况，例如先手动添加，然后又运行了 mint agent setup，或者安装了 Cursor 插件后又运行了 setup。保留一个条目并移除其他条目。各工具的具体步骤请参阅断开或撤销访问权限。