Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion ai/mintlify-mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -107,21 +107,23 @@

The AI tool acts as you on the deploy branch:

- **Edits are live to collaborators.** Anyone else editing the deploy branch in the dashboard sees the AI's changes as they happen.

Check warning on line 110 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L110

Did you really mean 'ato'?
- **`publish` publishes only your changes.** It commits your pending changes straight to the deploy branch, like clicking **Publish** in the editor. Other people's unpublished changes stay pending. Your own unpublished edits from the dashboard editor publish too.
- **`discard` reverts only your changes.** It returns `discardedChanges` with the number of changes it reverted. Other people's changes and the branch itself stay untouched.
- **`status` lists only your changes.**

Internal projects have no docs site, so they have no publish step. When `list_deployments` returns `projectType: "workspace"`, Mintlify commits edits to the deploy branch automatically, including uploaded images.

Mintlify tracks changes per page. If you and someone else both edited the same page, `publish` publishes the whole page and `discard` reverts the whole page, including the other person's edits.

Mintlify refuses edits to the deploy branch, and changes nothing, when any of the following is true:

- **Push directly to your deploy branch** is off in your [publishing settings](#publishing).
- Branch protection on your deploy branch requires pull requests, or Mintlify can't check your branch protection rules.
- Editing the deploy branch is locked in the dashboard editor.

Check warning on line 123 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L123

In general, use active voice instead of passive voice ('is locked').
- You connected with a client or machine-to-machine token instead of an OAuth login. These tokens aren't tied to a user, so they have no "own" changes.

Mintlify checks these conditions on every edit and caches your branch protection rules for up to 30 seconds. Comment tools still work on the deploy branch when edits to it are refused. If your deploy branch starts requiring a pull request after you edit it, `publish` returns `branch_protected` and your changes stay pending. Open the dashboard editor to move them to a new branch.

Check warning on line 126 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L126

In general, use active voice instead of passive voice ('are refused').

## Work on a branch

Expand All @@ -141,7 +143,7 @@

This toggle shares the same `agentReviewProcess` setting as the Slack and dashboard agent, so any change here also applies to those flows.

The toggle is disabled in three cases:

Check warning on line 146 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L146

In general, use active voice instead of passive voice ('is disabled').

- **Your deploy branch requires a pull request.** If branch protection rules or required approvals prevent direct pushes, MCP changes always go through a pull request regardless of this setting.
- **Mintlify hosts your project.** For Mintlify-hosted sites, MCP changes always push directly, unless branch protection still requires a pull request.
Expand Down Expand Up @@ -176,7 +178,7 @@

### Images

- **`upload_image`**: Start uploading a local image file to `branch`. Pass the destination `path` (for example, `images/dashboard.png`), the file's `contentType`, and its exact `size` in bytes. Returns an `uploadId`, a presigned `uploadUrl`, and the `headers` to send with the upload.

Check warning on line 181 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L181

Did you really mean 'contentType'?

Check warning on line 181 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L181

Did you really mean 'uploadId'?

Check warning on line 181 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L181

Did you really mean 'uploadUrl'?
- **`finalize_image_upload`**: Save the 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_image`, the AI tool uploads the file bytes to `uploadUrl` with a `PUT` request and the returned headers. For example:
Expand All @@ -192,7 +194,7 @@
Work with the [comments and suggestions](/editor/collaborate#comments) 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.

Check warning on line 197 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L197

Did you really mean 'threadId'?

Check warning on line 197 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L197

Did you really mean 'no_match'?
- **`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, and an optional `note` to explain the change. 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.
Expand Down Expand Up @@ -238,7 +240,7 @@
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 `update_config` for `docs.json` settings.
- **`manage_custom_domain`**: Add or remove a custom domain, provision its hostname, or retrigger hostname validation.

Check warning on line 243 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L243

Did you really mean 'retrigger'?
- **`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](/deploy/authentication-setup), add or delete passwords, configure end-user authentication, or switch which one is active.
- **`manage_workflow`**: Create, update, enable or disable, delete, or trigger a workflow.
Expand All @@ -253,13 +255,13 @@

### Branches and publishing

- **`list_deployments`**: List the projects your connection can access, returning each `{subdomain, name}`. Call this to discover which `subdomain` to pass.
- **`list_deployments`**: List the projects your connection can access, returning each `{subdomain, name, projectType}`. `projectType` is `site` for a docs site or `workspace` for an internal project. Call this to discover which `subdomain` to pass.
- **`create_branch`**: Start a new branch off your deploy branch with a `title` that also names its pull request. Returns the `branchName` to pass as `branch`. See [Work on a branch](#work-on-a-branch). You don't need it to [edit the deploy branch directly](#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. 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`.

Check warning on line 263 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L263

In general, use active voice instead of passive voice ('are allowed').
- **`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.

Check warning on line 264 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L264

In general, use active voice instead of passive voice ('was rolled').

Check warning on line 264 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L264

In general, use active voice instead of passive voice ('is pinned').
- **`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.

## Example prompts
Expand All @@ -279,7 +281,7 @@
</Accordion>

<Accordion title="Review every PR">
The admin MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes.

Check warning on line 284 in ai/mintlify-mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/mintlify-mcp.mdx#L284

Cut or rephrase 'powerful'. See 'Phrases to cut' in the style guide.
</Accordion>

<Accordion title="Keep branches focused">
Expand Down
Loading