Skip to main content
The admin MCP exposes the following tools. AI tools choose which tools to call based on your prompt. For how the editing and publishing tools fit together, see Edit and publish with the admin MCP.

Content

  • read: Fetch the full MDX of any page on branch, or on your deploy branch when you omit it. Pass a page path, such as guides/setup, or the last segment of an editor URL, which is the page ID with an optional title in front of it. When you use a page ID from an editor URL, pass the branch from that URL as branch. The response includes a filePath that you can pass as path to edit_page and write_page, and a version of the content it returned. Pass forEdit: true to read the live page instead of its saved copy. Use forEdit: true before you overwrite the page with write_page. To read a private page, pass its private-page-<uuid> node ID from list_nodes with visibility: "private". Private reads don’t need a branch and require an OAuth session. The admin MCP rejects client and machine-to-machine tokens for private-page access.
  • search: Search the pages on branch by meaning and exact wording, or your deploy branch when you omit it. Pass a question, topic, name, or exact phrase as query. By default, search returns the most relevant pages first as results. Each result has the page’s path and title, and snippets with the matching lines. When search is confident in the top result, that result also includes the page’s full content, up to 16 KB. The next results include the section around their best match. Pass limit to return up to 20 pages (default 6). To list every page that contains a phrase, such as before a rename, pass mode: "all" (default limit 100, maximum 500). Passing regex: true treats query as a regular expression and always uses mode: "all".
  • edit_page: Apply a targeted edit to a page. Pass path in the same forms as read. Pass oldString and newString for one replacement, or pass an edits list of up to 100 replacements to change several parts of a page in one call. Mintlify applies the edits in order, each to the result of the previous one. If any edit fails, none of them apply. Like write_page, edit_page returns notRendered for markup the edit adds that the editor drops. It doesn’t report markup that was already on the page. To edit a private page, pass its private-page-<uuid> node ID as path. Private edits require an OAuth session with an editor role or higher on the page and don’t need a branch.
  • write_page: Overwrite a page’s full MDX content. Pass path in the same forms as read. Before you overwrite a page, call read with forEdit: true and pass the returned version to write_page as baseVersion. If the page changed since that read, Mintlify refuses the write, changes nothing, and returns page_changed. Read the page again and reapply your change. If you omit baseVersion on a page that has content, write_page returns base_version_required. A page with only frontmatter doesn’t need a baseVersion. Also accepts a private-page-<uuid> node ID to overwrite a private page under the same OAuth and role requirements as edit_page. Use create_node to create a new private page. If the content includes markup the Mintlify editor drops, such as <script> tags, <style> blocks, event handlers like onClick, or JavaScript expressions, the response includes a notRendered field. Each entry lists the dropped element, its line, why the editor drops it, and what to use instead, such as Tailwind classes, inline style={{}} objects with literal values, or Mintlify components like accordions and tabs.
  • read_page_history: List a page’s saved version history on branch, or on your deploy branch when you omit it. Pass path in the same forms as read, including a private-page-<uuid> node ID. Returns versions, newest first, and a nextCursor. Each version has a versionId, createdAt, and authors, each with a name and a type of user, git, or system. Pass limit to return 1 to 50 versions per call (default 20), and pass nextCursor back as cursor to list older versions. Pass a versionId to get that version’s full MDX as content. The tool is read-only. To restore an earlier version, call read on the page with forEdit: true, then pass the earlier version’s content to write_page with that read’s version as baseVersion. If that version contains inline data that’s no longer on the page, write_page can’t restore it. Restore that version from version history in the editor instead. Errors include page_not_found, version_not_found, and invalid_cursor.

Inline data

Pages can embed images and other files as base64 data URLs. To keep responses small, read, search, diff, read_page_history, and read_comments replace each base64 payload of 1,000 characters or more with a placeholder such as [elided 48210 chars #1234567890]. Keep these placeholders unchanged when you pass content back. edit_page, write_page, create_node, and suggest_edit replace each placeholder with the original data from the current content of the target page. If a placeholder doesn’t match data on the target page, Mintlify refuses the write, changes nothing, and returns inline_data_unresolved. Copy placeholders only from a read of the same page. If Mintlify can’t read the page to restore placeholders, it returns inline_data_source_unreadable and changes nothing. Try the call again.

Uploads

  • upload_file: Start uploading a local file. Pass the destination path, the file’s contentType, and its exact size in bytes. Returns an uploadId, a presigned uploadUrl, and the headers to send with the upload.
  • finalize_file_upload: Save an uploaded image to branch. Pass the uploadId and the same path. Returns the src to reference in MDX with edit_page or write_page, or in the logo or favicon fields of docs.json with update_config.
After upload_file, the AI tool uploads the file bytes to uploadUrl with a PUT request and the returned headers. For example:
To add an image, pass an image path, such as images/dashboard.png, and the branch to upload_file. After the upload, call finalize_file_upload. Mintlify checks that the uploaded file’s contents match its extension before saving it. An upload to an existing path replaces that image. Only logo and favicon uploads can be SVG files: pass purpose: "logo" to both tools when you upload one. Page images can’t be SVG. Saved images appear in status and publish with your other edits when you call publish. To write a page from a local Markdown file, pass a .md or .mdx path with contentType set to text/markdown or text/plain. Page uploads don’t need a branch or finalize_file_upload. After the upload, pass the uploadId in place of content to write_page, or as data.uploadId to create_node. This avoids resending a large page’s full content in the tool call. Use the uploadId within 10 minutes. Each uploadId works once, on the same project and for the same user or client that created it. Mintlify deletes the uploaded file after the write. A reused or expired uploadId returns upload_not_found.

Comments

Work with the comments and suggestions that your team leaves in the dashboard editor.
  • read_comments: List the open comment and suggestion threads on a page, oldest first. Pass path in the same forms as read. Each thread includes a threadId, its type (comment or suggestion), the quotedText it’s anchored to, the suggestedText for suggestions, and its comments with each author, content, and createdAt. If the anchored text no longer exists on the page, the thread includes anchorRemoved: true and quotedText shows the original quote. Reads threads on branch, or on your deploy branch when you omit it.
  • add_comment: Start a new comment thread on a page without changing its content. Use it to leave feedback for your team instead of editing. Pass path in the same forms as read, the content of the comment, and quotedText: the smallest unique span of visible text to anchor to, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. For example, quote custom domain, not [custom domain](/path). Returns the new threadId. If the text isn’t on the page, the error is no_match. If it matches more than once, the error is not_unique, so quote a longer span.
  • suggest_edit: Propose a tracked-changes suggestion on a page instead of editing it. The original text stays on the page with a strikethrough and the replacement appears alongside it. Nothing changes until someone accepts or rejects the suggestion in the dashboard editor. Pass path in the same forms as read, oldString, and newString. oldString is the smallest unique span of visible text to replace, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. Pass an empty newString to suggest a deletion. Pass an optional comment to explain why the change helps. Mintlify posts it as the agent’s reply in the suggestion thread. The older note parameter still works as a deprecated alias for comment. Returns the new threadId with the originalText and suggestedText, trimmed to the span that changes. If the same suggestion is already open, the response includes alreadyExists: true and the existing threadId. The no_match and not_unique errors work as they do for add_comment. The error is no_change when both strings are the same, and conflicting_annotation when the text overlaps another open suggestion.
  • reply_to_comment: Reply to a thread by threadId with content. Pass resolve: true to also resolve the thread. Mintlify posts the reply as the agent on behalf of the authorizing user, and it appears live in the dashboard editor.
  • resolve_comment: Resolve a thread without replying.
  • read_inbox: List your dashboard inbox on a project, newest activity first. The inbox includes comments and mentions, suggested edits, review requests, and private pages and folders shared with you. By default, read_inbox returns open items. Pass state as open, done, or all, and section as comment, suggestion, invitation, request, or all (default). The request section includes review requests and invitations. Pass filter to narrow comments to mentions or on-my-page (pages you own), or suggestions to those from people or the agent, or the request section to requests or invites. The filter must match section unless section is all. Pass dateFrom and dateTo as ISO 8601 date-times to limit items by their latest activity. Pass limit for 1 to 50 items per call (default 20), and pass nextCursor back as cursor to list older items. Each item includes its category, state, latestActivity, and target. When target.thread is present, unresolved, and not on a private page, call read_comments with its filePath and reply with reply_to_comment, both on its branch. restricted items don’t include thread details. read_inbox is read-only and never marks items as read or done. Errors include invalid_filter, invalid_date_range, and invalid_cursor.
add_comment, suggest_edit, reply_to_comment, and resolve_comment require an OAuth session and a branch. They act on the threads left on that branch, and work on your deploy branch even when edits to it require a pull request. You can reply to suggestion threads, but you must accept or reject suggestions in the editor. Comments on private pages aren’t available through the admin MCP. read_inbox also requires an OAuth session, and only returns the inbox of an active member of the project’s organization.
  • list_nodes: Walk the navigation tree of branch, or of your deploy branch when you omit it, with optional filters. Filter by parentId (use recursive: true to include all descendants), one or more node types, or any division scope: language, version, tab, dropdown, anchor, product, or item. Uploaded files and folders (file and file_directory nodes) appear only when you include them in the type filter. Each node returns its id, type, text, and parent, plus path, pageId, and hidden when they apply. Pass a page’s path to read to get its content and frontmatter. Results paginate through an opaque cursor. Pass visibility: "private" to list the private pages and folders the OAuth user can access instead of the branch navigation tree. Private listing ignores branch and the other filters, and returns each node’s role.
  • create_node: Add a new page, group, tab, anchor, version, language, product, or dropdown. Pass visibility: "private" with data.type: "page" or data.type: "group" to create a private page or private folder in the caller’s private tree. The caller becomes the node’s manager. Private creation requires an OAuth session, doesn’t need a branch, and places the node at the private root or under an existing private-folder-<uuid> parent. For new pages, the response includes an editorUrl that opens the page in your dashboard. If a page already exists at the path on branch, create_node writes the new content into that page instead of failing. The page keeps its place in the navigation, even if you pass a different parent, and the response includes updated: true. If Mintlify adds a new page to the navigation but can’t save its content, create_node returns PAGE_SEED_FAILED. Call create_node again with the same path to write the content.
  • update_node: Update a node’s properties in place (rename a group, change an icon, set a default version). Accepts a private-page-<uuid> or private-folder-<uuid> node ID to rename a private page or folder or change its icon or tag. Private updates require an OAuth session with an editor role or higher and don’t need a branch.
  • move_node: Move a node, including renaming a page’s path.
  • delete_node: Remove a node from the navigation. Accepts a private-page-<uuid> or private-folder-<uuid> node ID to delete a private page or folder from the caller’s private tree. Private deletions require an OAuth session with a manager role on the node and don’t need a branch.
If a create_node, update_node, move_node, or delete_node call leaves the navigation in an invalid state, the response includes a navigationErrors field that describes the problem. For example, a page placed at the root next to tabs returns navigationErrors. Mintlify can drop invalid nodes from the published navigation, so fix these errors before you call publish.

Configuration

  • update_config: Change top-level docs.json settings, such as theme, colors, logo, navbar, footer, redirects, integrations, and SEO. It can’t change navigation; use the navigation tools instead. Mintlify rejects an invalid configuration as a whole.

Mintlify skill

  • read_skill: Read Mintlify’s guide to writing docs, which covers pages, components, widgets, navigation, and docs.json. It’s the same Mintlify skill that the agent uses. Call it without path to get SKILL.md, the skill’s index, and a files list of its reference files. Pass a file from that list as path, such as reference/widgets.md, to read it. The tool is read-only and doesn’t need a subdomain or branch. If the file doesn’t exist, it returns skill_file_not_found with the files list.
The index response also includes a skills list of your organization’s and your own agent skills that are turned on, each with a name, description, and path. Pass a skill’s path, such as org/release-notes/SKILL.md, to read its instructions. The response lists the skill’s reference files in files, and you can pass any of them as path. Personal skill paths start with me/ and appear only for OAuth sessions. The admin MCP tells AI tools to call read_skill before they write, restructure, or style pages, and to follow any organization or personal skill whose description fits the task.

Project management

Project management tools handle project-level operations, such as managing automations, project settings, custom domains, Git sources, authentication, members, analytics, and private page sharing. They act on the live project, not on a branch. Each tool takes a subdomain for the project to act on. Organization-wide connections must pass subdomain. Call list_deployments to find it. Read tools also accept subdomains, a list of up to 25 projects, and return a result or error for each one. Most tools take a request object whose action field selects the operation. For example:
Read tools:
  • get_deployment_settings: Read a project’s dashboard settings, including editor publishing and Reviewing settings, Git sources, custom hostname status, and source checks in one call. Slack configuration and snippets are opt-in.
  • get_analytics_report: Read a prebuilt analytics report, such as page views, popular pages, referrals, feedback, assistant chats, or search quality. Select the report with request.report. Large results paginate with maxRows and rowOffset. For custom queries, use query_analytics.
  • get_analytics_schema: Read the tables, events, and SQL rules that query_analytics accepts. The AI tool calls it once before writing a query.
  • query_analytics: Run one read-only SELECT query on your site’s analytics, such as page views, search, assistant, feedback, and traffic. Results are already scoped to the project. If analytics queries aren’t enabled for the project, both analytics query tools return a not_enabled error.
  • get_workflows: List automations, get one automation, or page through its runs.
  • list_repos_and_prs: List connected repositories, a repository’s pull requests, or available integrations to use in an automation.
Write tools:
  • update_deployment_settings: Change one dashboard setting, such as noindex, base_path, name, disable_ai_chat, search_settings, privacy, custom_scripts, or an add-on. Use editor_publishing to change Reviewing settings. Only org admins can change them, with the same rules as the dashboard. Use update_config for docs.json settings.
  • manage_custom_domain: Add or remove a custom domain, provision its hostname, or retrigger hostname validation.
  • manage_git_source: Add, update, remove, or reorder the Git repositories a project builds from, or set the base source.
  • manage_access_auth: Configure or remove site authentication, add or delete passwords, configure end-user authentication, or switch which one is active. Switching carries over only a JWT configuration. If the active configuration uses any other type, the switch fails with a 409 error and leaves your site unchanged. To change to a different type, configure the new authentication directly. When an action turns on site authentication, including a switch from end-user authentication, Mintlify deletes existing previews that don’t have organization login or password protection. Set previewDeployments to delete_unauthenticated (default), delete_all, or keep to choose what happens to existing previews.
  • manage_workflow: Create, update, enable or disable, delete, or trigger an automation. In a multi-repository project, pass an optional repo_name (for example, mintlify/docs) when you create or update an automation to set its target repository. The repository must be connected to the project. If you omit it, new automations use the base source and updates keep the current target.
  • manage_workflow_prs: Merge or close a pull request that an automation run opened. To merge a pull request for a branch the AI tool edited, use publish with merge: true instead.
  • manage_members_sharing: List, invite, or remove organization members, update their roles, or manage private page grants and moves in bases. One call invites up to 250 people and skips anyone who is already a member or has a pending invite.
Write tools return the project’s updated state under state, so the AI tool can confirm the change without a second call. Each action checks the connection’s granted scopes and your dashboard role. An action you aren’t authorized for returns an error such as insufficient_scope. To fix it, see Tool calls return insufficient_scope.
Project management writes apply immediately to the live project. They don’t create a branch or open a pull request. Confirm the intended change before prompting an AI tool to update automations, settings, domains, authentication, or members.

Review requests

These tools appear only when your project requires review before publishing. list_review_requests and request_review take an optional branch, which defaults to your deploy branch. On another branch, a review request covers the branch’s changes against your deploy branch. If your deploy branch has GitHub branch protection, request reviews on a feature branch.
  • list_review_requests: List the open review requests on a branch. Each request includes its requester, its reviewers and their state, and its pages. Each page has a path, title, and approval of approved, pending, or stale if the page changed after approval and needs another review. Changes that don’t belong to a page, such as navigation and site settings, appear as one item titled Site changes.
  • request_review: Ask reviewers to approve your pending changes. Pass up to 100 pages in the same forms as read, and the reviewers, each as an email or a role. role: "admin" asks every admin. role: "editor" asks every publisher, or every editor if your organization doesn’t have the publisher role. If you have pending changes that don’t belong to a page and no other open request includes them, Mintlify adds the Site changes item to the request. Mintlify only asks active members, other than you, who can approve. Each reviewer gets an email and an inbox item. Errors include no_pending_changes when a page has nothing to review, no_reviewers when no one who can approve matches reviewers, and review_unavailable when the branch can’t take review requests, such as a protected deploy branch.
  • add_reviewers: Add reviewers to an open review request by requestId, without withdrawing it, like adding reviewers in the editor. Pass reviewers in the same forms as request_review. Existing approvals stay. Mintlify skips the requester, people already on the request, and members who can’t approve, and only new reviewers get an email and an inbox item. Returns the updated request and the added emails. Errors include request_not_found and no_reviewers.
  • withdraw_review_request: Withdraw a review request you made by requestId. Pass a reviewer email to remove only that reviewer. Removing the last reviewer withdraws the request. The pages keep their pending changes.
  • approve_review_request: Approve someone else’s review request by requestId, like clicking Approve in the editor. The admin MCP tells the AI tool to approve only when you ask it to approve that specific request, and to confirm the requester and pages with you first. Returns own_request for your own request, own_branch for a branch you created, not_reviewer if your role can’t approve, changed if the changes were edited since the AI tool read them, and github_rejected if GitHub refused the approval, for example because you haven’t connected your GitHub account. On a protected GitHub branch, approving also approves the pull request in GitHub as your connected account.
  • publish_review_request: Publish an approved review request by requestId, with a title for the commit message, like publishing a teammate’s approved changes in the editor. Admins and publishers can publish. The admin MCP tells the AI tool to publish only when you ask it to publish that specific request. Returns not_approved until every page has the approvals it needs, navigation_held while another open request holds navigation changes that this request needs, and not_allowed if your role can’t publish. On a feature branch, it merges the branch’s pull request into your deploy branch and returns merged. It returns no_pull_request if the branch has no pull request yet, so call publish on the branch first, and merge_not_allowed if you must merge in the editor. Follow the returned deployment with deployment_status.

Branches and publishing

  • list_deployments: List the projects your connection can access, returning each {subdomain, name, projectType}. projectType is site for a site or workspace for a knowledge base. Call this to discover which subdomain to pass.
  • create_branch: Start a new branch off your deploy branch, or off the existing branch you pass as from, with a title that also names its pull request. Returns the branchName to pass as branch. See Work on a branch. You don’t need it to edit the deploy branch directly.
  • list_branches: List Git branches available for a project’s repository, with optional query filtering. Returns the branch names, total count, and the deploy branch. Pass any of them as branch.
  • status: List the edited files, changed docs.json keys, and pending navigation diff on branch, or on your deploy branch when you omit it. On the deploy branch, lists only your changes.
  • diff: List all changes between branch and your deploy branch. Each changed file and docs.json entry includes authors and byYou. authors lists the members whose unpublished edits the entry contains. byYou is true when the entry includes your own edits. Use byYou to tell your changes apart from a colleague’s on a shared branch.
  • publish: On the deploy branch, commit only your pending changes directly. If your project requires review and you aren’t an admin, returns review_required on the deploy branch or when you pass merge: true. See Projects that require review. On a branch, commit pending changes and return the branch’s pull request, opening one if needed. Pass merge: true to also merge the pull request when edits to the deploy branch are allowed. When the changes reach the deploy branch, also returns a deployment status to follow with deployment_status.
  • deployment_status: Check whether published changes are live on your docs site. Pass the commitSha from publish, or omit it to check the latest deploy. Returns a state of pending, queued, building, live, not_live, failed, or skipped, along with live and a message to share with you. not_live means the site still serves an earlier version, for example because the deploy was rolled back or your deployment is pinned to an earlier version.
  • discard: Abandon the edits on branch. On the deploy branch, reverts only your pending changes. On another branch you created, deletes the branch and closes its pull request.