Mintlify MCP

View saved version →

---
name: editing-docs-content
description: Use when changing the text or MDX body of documentation pages through the Mintlify Admin MCP — fixing typos, rewriting sections, updating code samples, or making any content edit that should ship as a commit or PR.
---

# Editing Docs Content

## Overview

Content edits happen inside a checked-out editing session on an isolated git branch. Nothing goes live until `save` publishes the branch. Every editor tool fails with "No active session" until you `checkout`.

## Workflow

1. `list_deployments` — find the subdomain (skip if pinned or already known).
2. `checkout { subdomain, slug: "fix-auth-typos" }` — opens the session (~7s). Surface the returned `editorUrl` to the user so they can follow along.
3. Locate content: `search { query }` greps every page on the branch (literal string by default, `regex: true` for regex, results capped at 30KB — refine if `truncated`). `read { path }` returns the full MDX of one page. Both reflect in-session edits immediately.
4. Edit:
   - Targeted change → `edit_page { path, oldString, newString, replaceAll? }` (string-replace, like a code editor Edit tool). `replaceAll` is per-page; a docs-wide sweep is one `edit_page` call per matched path from `search`.
   - Full rewrite → `write_page { path, content }`.
   - If a search hit might sit in frontmatter rather than body, `read` the page first — frontmatter fixes go through `update_node`, not `edit_page`.
5. Verify with `diff` (patch per changed file) or `get_session_state` (branch, edited files, nav diff).
6. `save { title, mode? }` — publishes (~10s).

## Save modes

| mode | Behavior |
|------|----------|
| `auto` (default) | Opens a PR; auto-merges only when the deployment's agent review setting is push-to-main and the deploy branch is unprotected (`merged: true` in the response) |
| `pr` | Opens a PR and always leaves it open for review |
| `commit` | Commits to the **session branch** in git without opening a PR — a snapshot, never a direct write to the deploy branch |

Saving again in the same session commits to the existing PR branch. `discard_session` abandons everything without publishing.

## Critical: frontmatter is not body content

`edit_page` / `write_page` are for the MDX **body only**. Frontmatter fields (`title`, `sidebarTitle`, `description`, `icon`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, …) round-trip through structured node metadata — set them with `update_node { nodeId, data: { type: 'page', ... } }`. The site-level description lives in `docs.json` via `update_config`.

## Common mistakes

- Editing frontmatter with `edit_page` — silently wrong; use `update_node`.
- Calling `read`/`edit_page` before `checkout` — "No active session".
- Assuming `save` merged: check `merged` in the response; most deployments leave the PR open.
- Paths are page hrefs (`/quickstart` or `guides/setup`), leading slash and `.mdx` optional.
- Renaming a page path: `move_node`, never a write to a new path plus delete.

View saved version →

---
name: managing-deployment-settings
description: Use when changing live deployment settings through the Mintlify Admin MCP — custom domains, authentication, git sources, AI assistant toggle, noindex, custom scripts, source checks, snippets — or when managing org members and roles.
---

# Managing Deployment Settings

## Overview

Deployment and member operations run through code mode (`execute_code`) with **no checkout and no PR safety net — every write hits the live deployment immediately**. Read current state first, confirm with the user before auth/domain changes, and re-read after writing.

**REQUIRED BACKGROUND:** the `using-code-mode` skill covers return semantics and `{ subdomain }` targeting.

## Namespace `deployment`

| Area | Methods |
|------|---------|
| Read state | `get({})` — subdomain, name, basePath, customDomains, noindex, plan, … |
| Identity | `updateName`, `updateBasePath` ('' or '/docs'), `updateNoindex` |
| Custom domains | `addCustomDomainV2` (returns DNS records to configure), `removeCustomDomain`, `createCustomHostname`, `getCustomHostnameStatus`, `retriggerCustomHostnameValidation`, `deleteCustomHostname` |
| Docs auth | `updateAuth` (jwt / oauth-with-client-secret / password / mintlify), `updateUserAuth` (shared-session / jwt / oauth), `toggleAuth`, `deleteAuth`, `deleteUserAuth`, `addAuthPassword`, `deleteAuthPassword`, `deleteAuthJwtKeyPair` |
| Git sources | `getGitSources`, `addGitSource`, `updateGitSourceItem`, `removeGitSource` (by index), `reorderGitSources`, `setBaseGitSource` |
| AI assistant | `updateDisableAiChat({ disableAiChat })` — `true` turns the assistant **off**; `updateChatConfig` tunes assistant behavior when it is on |
| Add-ons | `updateAddOnFeedback`, `updateAddOnRelatedPages`, `updateSearchSettings`, `updatePrivacyConfig`, `updateCustomScripts` |
| Quality checks | `getSourceChecks`, `updateSourceChecks` (link-rot, spellcheck) |
| Editor publishing | `updateEditorPublishingSettings` (PR instructions, draft default, merge method) |
| Snippets | `getSnippets` |

Several auth/domain methods require a user-authorized token; `unauthorized` errors mean the token lacks the scope or user grant, not that the method is wrong.

## Namespace `members` (org-scoped)

These operate on the organization, not a single deployment: `listMembers({ includeRoles? })` (pass `includeRoles: true` to get each member's roles — omitted by default), `updateMemberRoles({ userId, roles })` (SSO-managed roles cannot be changed), `removeMember({ userId })`.

## Example: audit before touching auth

```
const current = await deployment.get({});
const sources = await deployment.getGitSources({});
({ current, sources });
```

## Common mistakes

- Writing without reading — always `deployment.get({})` first and echo the plan to the user for auth, domain, or member removals.
- Guessing payload shapes — `updateAuth`/`updateUserAuth` are discriminated unions; pull the schema via `search_code_operations` first.
- Removing git sources by guessed index — list first, indices shift after removal.
- Renaming preview deployments — `updateName` rejects them.
- Expecting a rollback path — there is no session/branch here; capture the pre-change state in the same script's logs.

View saved version →

---
name: managing-navigation
description: Use when adding, renaming, moving, or deleting docs pages, groups, tabs, anchors, versions, languages, or products in the navigation tree through the Mintlify Admin MCP, or when restructuring the sidebar.
---

# Managing Navigation

## Overview

Navigation is a tree of typed nodes edited with dedicated node tools inside a checked-out session — never through `update_config` (which rejects the `navigation` key). Node types: `page`, `group`, `tab`, `anchor`, `version`, `language`, `product`. Parent/child compatibility is enforced (groups cannot contain tabs; pages have no children).

## Explore first

`list_nodes` filters the tree: `parentId: null` = root nodes, `recursive: true` = all descendants (pair with omitted/null `parentId` to dump the whole tree), `type` = single type or array, plus `language`/`version`/`tab` scope filters. Paginates via `cursor`/`nextCursor` (limit max 500). You need real `nodeId`s from here before any mutation.

**Finding a page's nodeId by path**: `list_nodes { type: 'page', recursive: true }` and match each node's `data.href` against the page path (the same path `search` results and `read` use). There is no direct path-lookup parameter.

## Quick reference

| Task | Tool |
|------|------|
| New page | `create_node { parentId, data: { type: 'page', path, content } }` (MDX validated) |
| New group/tab/version/… | `create_node` with that type's name-shaped `data` |
| Rename group, set page frontmatter, change icon | `update_node { nodeId, data }` — partial merge, `data.type` must match stored type |
| Reorder or reparent | `move_node { nodeId, parentId?, order? }` — at least one required; `order` is 0-based; `parentId: null` = root |
| Rename a page's URL path | `move_node` (path/`href` is immutable in `update_node`) |
| Remove node + subtree | `delete_node { nodeId }` — returns `deletedNodeIds` |
| Redirect after deletion | `update_config { op: 'add_redirect', redirect: { source, destination, permanent? } }` — point `destination` at the closest surviving replacement page |

## Page frontmatter lives here

`update_node` with `data.type: 'page'` is the correct tool for `title`, `sidebarTitle`, `description`, `icon`, `tag`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, `deprecated` — the merged fields serialize back into the MDX `---` block on save. `edit_page` must not touch frontmatter.

## Common mistakes

- Deleting a published page without adding a redirect — breaks inbound links; pair `delete_node` with `add_redirect`.
- Trying to set `href`/`pageId` via `update_node` — rejected as immutable; use `move_node`.
- Moving nodes across version/tab/language/product boundaries unintentionally — allowed, but the response flags `crossedBoundary: true`; check it.
- Guessing `nodeId`s — always fetch them from `list_nodes` first.
- Forgetting `save` — nav edits stay on the session branch until published.

View saved version →

---
name: managing-workflows
description: Use when creating, updating, enabling, disabling, triggering, or debugging Mintlify Workflows (scheduled or push-triggered docs automations) through the Admin MCP, or when checking why a workflow run failed.
---

# Managing Workflows

## Overview

Workflows are deployment-level automations managed through code mode (`execute_code`) — no checkout needed, and changes apply to the live deployment immediately.

**REQUIRED BACKGROUND:** read the `using-code-mode` skill first for script return semantics and `{ subdomain }` targeting.

## Methods (namespace `workflows`)

| Method | Notes |
|--------|-------|
| `listWorkflows({})` | All workflows on the deployment |
| `getWorkflow({ workflowSchemaId })` | One workflow |
| `createWorkflow({ name, on, ... })` | Enforces plan limits and trigger validation |
| `updateWorkflow({ workflowSchemaId, ... })` | Dashboard validation path |
| `setWorkflowEnabled({ workflowSchemaId, enabled })` | Enabling re-checks plan limits |
| `triggerWorkflow({ workflowSchemaId })` | Manual run; enforces monthly run limits |
| `deleteWorkflow({ workflowSchemaId })` | Soft delete |
| `listWorkflowRuns({ workflowSchemaId?, status? })` | Run history, filterable |

Triggers (`on`) are either push-based (`{ push: [{ repo, branch?, isDeploymentGitSource? }] }`, max 10 repos) or cron (`{ cron: '0 9 * * 1' }`). Fetch the exact current schema with `search_code_operations { query: 'create workflow', namespace: 'workflows' }` before creating — the full `inputSchema` comes back in the hit.

## Example: find why runs are failing

```
const wfs = await workflows.listWorkflows({});
const runs = await workflows.listWorkflowRuns({ status: 'failed' });
({ workflows: wfs, failedRuns: runs });
```

## Common mistakes

- Guessing the `createWorkflow` payload — it is a large validated union; pull the schema via `search_code_operations` first.
- Forgetting these writes are live — disabling or deleting a workflow takes effect immediately.
- Triggering repeatedly to "retry" — manual triggers count against monthly run limits.
- Checking out an editor session first — workflows are code-mode, not session-scoped.

View saved version →

---
name: reviewing-analytics
description: Use when reporting on docs traffic, search quality, AI assistant usage, feedback, or billing-period usage through the Mintlify Admin MCP — questions like "what are people searching for", "which pages are popular", "how many chat messages this month", or "what gets zero results".
---

# Reviewing Analytics

## Overview

All analytics live in the code-mode `analytics` namespace (`execute_code`, no checkout, all read-only, scope `analytics:read`). Most methods take `dateFrom`/`dateTo` as ISO or `YYYY-MM-DD` strings; list endpoints are cursor-paginated.

**REQUIRED BACKGROUND:** the `using-code-mode` skill covers return semantics and `{ subdomain }` targeting.

## Method map

| Question | Methods |
|----------|---------|
| Overall traffic/engagement | `getInsights({})`, `getKpi`, `getPopularPages({ dateFrom, dateTo, trafficSource? })`, `getReferrals`, `getTopAgents` |
| What are people searching | `getSearchAnalytics({ dateFrom, dateTo, limit?, cursor? })`, `getTotalSearches`, `getUniqueSearchQueries`, `getSearchTimeSeries`, `getSearchClickThroughRate` |
| Search gaps | `getZeroResultSearches`, `getZeroResultSearchCount` |
| MCP search traffic | `getMcpSearchAnalytics`, `getMcpSearchTimeSeries`, `getMcpSearchTotalSearches` |
| AI assistant usage | `getAssistantAggregate`, `getAssistantCallerStats`, `getAssistantUsageSummary`, `getChat` (conversation list) |
| Reader feedback | `getFeedback` (thumbs aggregate), `getDetailedFeedback`, `getDetailedFeedbackSummary`, `getDetailedFeedbackById` |
| Billing-period usage | `getUsageSummary({ usageType })`, `getUsageHistory` — usageType: `CHAT_MESSAGE`, `PDF_PAGE`, `TRANSLATION_TOKEN_INPUT`, `TRANSLATION_TOKEN_OUTPUT` |

`getUsageSummary` takes only `usageType` (no dates) and always reports the **current billing period** — quota, period usage, and remainder. `getAssistantUsageSummary` is the assistant-specific view of the same billing meter, while `getAssistantAggregate`/`getChat` are date-ranged analytics windows — use the usage methods for "how much of my quota", the analytics methods for "what happened between these dates".

`trafficSource` on traffic methods is `'all' | 'ai' | 'human'` — useful for splitting agent vs human readership.

## Example: monthly search-quality report

```
const range = { dateFrom: '2026-06-01', dateTo: '2026-06-30' };
const top = await analytics.getSearchAnalytics({ ...range, limit: 50 });
const zero = await analytics.getZeroResultSearches(range);
const ctr = await analytics.getSearchClickThroughRate(range);
({ top, zero, ctr });
```

## Common mistakes

- Guessing parameter names — `getChat` uses `currentDateFrom`/`currentDateTo` (not `dateFrom`); verify with `search_code_operations { namespace: 'analytics', query: ... }`.
- Ignoring `cursor` on list endpoints and reporting a truncated picture.
- Requesting huge ranges in one call and hitting `truncated: true` — page or narrow the range.
- Comparing AI vs human traffic without setting `trafficSource`.

View saved version →

---
name: updating-site-config
description: Use when changing docs.json through the Mintlify Admin MCP — theme, colors, logo, favicon, navbar, footer, fonts, SEO metadata, site name or description, banners, redirects, or any site-wide setting.
---

# Updating Site Config

## Overview

`update_config` (inside a checked-out session) edits any top-level `docs.json` field except `navigation`. Changes land on the session branch and publish via `save`, like content edits. The full field reference is https://www.mintlify.com/docs.json.

## Operations

**`set`** — merge at the top level only. Each top-level key you provide **replaces that key's entire value**; sibling keys you omit are untouched, but nested fields inside a key you provide are not merged.

```
update_config {
  op: 'set',
  docsConfig: { name: 'Acme Docs', colors: { primary: '#0D9373', light: '#07C983', dark: '#0D9373' } }
}
```

Sending `colors: { primary: '#0D9373' }` alone would drop `colors.light` and `colors.dark`. There is no config-read tool, so use this recovery loop: send the `set`, then inspect the returned `diff` — it reports the `before` values of everything you changed, including nested fields you accidentally dropped. If the diff shows unintended removals, re-`set` that key with the complete object reconstructed from the diff's `before` values. Nothing is live until `save`, so this loop is safe.

Set a top-level key to `null` to remove it entirely. The merged result is validated against the full schema — any violation rejects the whole call with no partial writes. `navigation` and `$schema` keys are rejected.

**`add_redirect`** — append to `redirects`:

```
update_config { op: 'add_redirect', redirect: { source: '/old-path', destination: '/new-path', permanent: true } }
```

Rejects on duplicate `source`. Sources match by exact string comparison against stored redirects — keep the leading-slash form consistent.

**`remove_redirect`** — `{ op: 'remove_redirect', source: '/old-path' }`. Rejects if the exact source string is not present.

## Response

Returns `{ diff }` of only what changed: scalars as `{ before, after }`, nested objects recurse under `{ changed }`, arrays (`redirects`, `navbar.links`) as `{ added, removed }`. Read the diff to confirm the merge did what you intended.

## Which description tool?

| Target | Tool |
|--------|------|
| Site-level SEO/social description (`docs.json` `description`) | `update_config` |
| One page's frontmatter `description` | `update_node` with `data.type: 'page'` |
| Text inside a page body | `edit_page` |

## Common mistakes

- Sending `navigation` through `set` — rejected; use the node tools (`create_node`, `move_node`, …).
- Sending a partial nested object — `set` replaces the whole top-level key; follow the diff-recovery loop above when you don't know the current nested values.
- Editing `docs.json` as if it were a page via `write_page` — config has its own tool and validation path.
- Forgetting `save` — config edits are session-scoped until published.

View saved version →

---
name: using-code-mode
description: Use when managing a Mintlify deployment beyond docs content — workflows, deployment settings, members, analytics — or whenever a task needs execute_code / search_code_operations on the Admin MCP.
---

# Using Code Mode

## Overview

`execute_code` runs a TypeScript/JavaScript script against the Admin MCP dashboard SDK in a sandboxed Cloudflare isolate. It needs **no checkout**, and writes apply **immediately to the live deployment** — there is no branch/PR safety net. Confirm with the user before destructive or customer-visible writes.

Available namespaces as top-level globals: `workflows`, `deployment`, `members`, `billing`, `integrations`, `analytics`, `deployments`, plus `console`. No outbound fetch, no secrets; each SDK call is gated by the OAuth scopes on the token. `deployment`, `analytics`, `workflows`, and `members` carry nearly all operations; `billing` and `integrations` are sparse or empty — enumerate with `search_code_operations { namespace: 'billing' }` before assuming a method exists. `members` operations are org-scoped, not per-deployment.

## Find the method first

`search_code_operations { query, namespace?, limit? }` is BM25 search over all SDK methods. Each hit includes the method's full JSON Schema `inputSchema`, so no extra lookup is needed. Pass `namespace` alone to enumerate everything in it (workflows, deployment, members, billing, integrations, analytics). Always search before writing a script — never guess method names or parameter shapes.

## Return semantics (the #1 footgun)

The script is wrapped in an async function; the value of the **last expression statement** becomes the result.

```
const summary = await analytics.getUsageSummary({ usageType: 'CHAT_MESSAGE' });
const insights = await analytics.getInsights({});
({ summary, insights });
```

- `await x.y();` alone on the last line works.
- A bare top-level `return X;` is **dropped**.
- `export default async function ...` returns the function object, not its result.

## Targeting deployments

Every namespace method takes an optional second argument `{ subdomain }`:

```
workflows.listWorkflows({}, { subdomain: 'acme' });
```

Omit it to use the token's default deployment. `deployments.list()` enumerates the org (requires `deployment:read`). Mixing subdomains in one run is fine.

## Result envelope

`{ ok: true, result, logs, truncated, durationMs }` or `{ ok: false, error: { code, message }, ... }`. Error codes: `unauthorized`, `invalid_json`, `invalid_request`, `misconfigured`, `timeout` (30s wall clock), `sandbox_error` (your script threw), `execution_failed` (worker plumbing). `truncated: true` = result/logs hit the size cap — narrow the query or page through.

## Common mistakes

- Using `return` at top level — result silently becomes undefined.
- Treating code-mode writes like session edits — they are live instantly; there is no `save`/`discard`.
- Guessing method signatures instead of calling `search_code_operations`.
- Calling `checkout` first — unnecessary for code mode.
- Trying `fetch` or Node APIs — the sandbox has neither.