SKILL.md

---
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.