Skip to content

Add mint agent setup to agent-only setup instructions #8223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 2 commits into from
Oct 31, 2026
Merged

Add mint agent setup to agent-only setup instructions #8223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e6f076
Add mint agent setup to agent-only setup instructions
ethanpalm Oct 31, 2026
ed902cb
Clarify Node.js requirement and post-deploy steps in agent workflow
ethanpalm Oct 31, 2026
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
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"instructions": [
"When working in a Mintlify project, run `mint instructions` for current step-by-step instructions for common tasks. If the command is unknown, run `npx mint@latest instructions`.",
"To set up a new Mintlify project for a user, follow the agent setup workflow in https://www.mintlify.com/docs/quickstart.md.",
"To connect a coding agent to a Mintlify project, offer to run `mint agent setup --agent <claude-code|codex|cursor>` in the project directory. It installs Mintlify skills and adds the admin MCP server to the agent's configuration, then the user completes OAuth sign-in. See https://www.mintlify.com/docs/cli/commands.md#mint-agent-setup.",
"For plans and pricing, see https://www.mintlify.com/pricing.md."
]
},
Expand Down
15 changes: 7 additions & 8 deletions snippets/agent-setup-workflow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,21 @@

If the user asks you to set up Mintlify, a documentation site, or a local Mintlify project, complete the following workflow yourself. Ask the user only for information or approvals you cannot supply. We recommend CLI onboarding. Web onboarding at [mintlify.com/start](https://mintlify.com/start) is also available if the user prefers it or you cannot run terminal commands.

1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release.
1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release. Note whether it is v22.20 or newer, which step 9 requires.
2. Run `mint --version`. If the command is unavailable, install the CLI with `npm i -g mint` or `pnpm add -g mint`. If the command succeeds, run `mint update`. Then run `mint instructions new-site` for current setup guidance, and `mint instructions` to list topics for later tasks.
3. Run `mint status` before starting authentication. If it already shows an organization, keep the existing session and do not create another account.
4. Run `mint login` if the user has an account. Otherwise, don't create an account now. You can publish without one using `mint deploy` in step 9, and the user creates their account when they claim the site. Don't run `mint signup` for the user: when an agent runs it, it prints the [agent signup guide](https://mintlify.com/auth.md) and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at [mintlify.com/start](https://mintlify.com/start).
4. Run `mint login` if the user has an account. Otherwise, don't create an account now. You can publish without one using `mint deploy` in step 10, and the user creates their account when they claim the site. Don't run `mint signup` for the user: when an agent runs it, it prints the [agent signup guide](https://mintlify.com/auth.md) and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at [mintlify.com/start](https://mintlify.com/start).
5. After `mint login`, run `mint status` again. Confirm that it reports their email, organization, and subdomain. If the organization exists but no subdomain appears, ask the user to finish selecting or connecting a GitHub repository in the onboarding browser tab, then retry.
6. If the user has an existing documentation repository, clone or open it. Preserve its content. For a new local project, scaffold into a new, empty directory with either `mint new <directory> --name <name> --theme <theme>` or `mint new <directory> --template <template-name>`. Ask which theme or template they want if they have not specified one. Do not use `--force` on a directory containing user files.
7. Run `mint dev --no-open` from the directory containing `docs.json` as a background process. Confirm the local URL loads, report it to the user, and stop the process when it is no longer needed.
8. Run `mint validate` and `mint broken-links`. Fix issues caused by your changes before continuing.
9. Publish when the user asks for a live site.
9. Offer to connect the user's coding agent to the project. If they agree and Node.js is v22.20 or newer, run `mint agent setup --agent <agent>` from the project directory, where `<agent>` is `claude-code`, `codex`, or `cursor`. It installs Mintlify skills and adds the [admin MCP](/ai/mintlify-mcp) to the agent's project configuration. Pass `--agent` because without an interactive terminal the command configures every agent it detects. The user completes OAuth sign-in in the agent afterward. See [`mint agent setup`](/cli/commands#mint-agent-setup).
10. Publish when the user asks for a live site.
- **Logged in with a Git repository:** commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content.
- **No account:** from the directory containing `docs.json`, run `mint deploy --subdomain <name>`, choosing a short name based on the project. Follow the steps it prints: clone the hosted repository into a separate directory, copy the docs into its root, commit, and push to `main` with the write token as an `Authorization: Bearer` header for that Git command only. Never show the token to the user, put it in a remote URL, or change the user's own Git remotes. See [Agent signup](/cli/agent-signup).
10. Verify that `https://<subdomain>.mintlify.site` loads before reporting that deployment is complete. If you logged in, run `mint status` to get the subdomain. If you used `mint deploy`, use the URL it printed, then hand the site to the user:
- Tell them the site expires unless they claim it.
- Ask for the email address that should own it. Never invent one.
- Run `mint claim --email <email>` from the same directory and share the claim link.
- When they return the code shown after they sign in, run `mint claim --code <code>`.
11. Verify that `https://<subdomain>.mintlify.site` loads before reporting that deployment is complete.
- **Logged in with a Git repository:** run `mint status` to get the subdomain. Skip the claim steps.
- **No account:** use the URL that `mint deploy` printed, then hand the site to the user. Tell them the site expires unless they claim it. Ask for the email address that should own it, and never invent one. Run `mint claim --email <email>` from the same directory and share the claim link. When they return the code shown after they sign in, run `mint claim --code <code>`.

Have the user complete browser actions only for claiming a site, OAuth approval, and connecting or authorizing GitHub. Keep ownership of the terminal workflow and resume after each user action. For command flags and troubleshooting, use the [CLI command reference](/cli/commands).

Expand Down
Loading