5 minutes read
Denzell Ford
Engineering
Share this article
Denzell Ford
Engineering
Share this article
We watched AI agents struggle to set up Mintlify. They fetched multiple docs pages, tried the wrong commands, and gave users long instructions instead of completing the task.
So we built setup.md, one page that tells any agent how to set up Mintlify, what commands to run, and what to tell the user.
Here's what we saw. Someone asks Claude.ai to "set up Mintlify for my team." It can't install anything, so it fetches the quickstart, CLI reference, and MCP page. Then it sends back 400 words explaining three install paths, two requiring a terminal the person doesn't have open. The person picks one and asks a follow-up. Setup still hasn't started.
Claude Code had a different problem. It could run commands, but called mint --help, fetched the docs twice, and pieced together an install. It often worked, but only after round trip after round trip. After all this trouble, the user would just go through normal onboarding on the dashboard, defeating the point of agent-assisted onboarding.
Why agents kept getting setup wrong #
Setup spans the Mintlify CLI, Admin MCP server, and Mintlify editor. Each had its own docs page, assuming the reader knew which one to use.
An agent only knows the user's request and what it last fetched. It might read the CLI page and try mint login in Claude.ai, which has no shell. Or it might read the MCP page from Codex and recommend a ChatGPT connector, useless for Codex. Every wrong turn meant another fetch and more explanation.
Agents don't explore. They follow what they think is correct or what "feels right." Our docs URL benchmark found this at scale: a single link to llms.txt eliminated most agent 404s. setup.md applies the idea behind our install.md proposal for LLM-executable installation to our own product.
A complete set of docs loses to one page that answers the task in front of the agent.
Asking the agent better questions #
The page opens with a question for the agent: can you edit files on this machine?
No. You're a hosted assistant, Claude.ai or ChatGPT. Walk the user through adding the Mintlify connector in Claude or the Mintlify app in ChatGPT.
Yes. You're a coding agent: Claude Code, Codex, Cursor, Antigravity, Grok Build. You do the setup yourself, verify it, and tell the user what changed. For the three most common clients it's one command:
npx -y mint@latest agent setup --global --agent claude-code
That installs the Mintlify skill and adds the mintlify-admin MCP server to the agent's own config. Each client also gets its own section for when the shortcut doesn't apply.
Before any of that, the page has the agent ask what the person is building. A private knowledge base is a Mintlify Base and gets created with mint deploy --base, no account needed until the claim. A public docs site goes through mint deploy. The agent never has to work out which product the user meant from context, because it asked.
Include user-guided prompts #
Agents are verbose by nature. They mention every single detail of the setup from the CLI: repository URLs, organization IDs, subdomains, file paths, and token expiry timestamps. Users have to sift through the output just to finish onboarding and find a link to claim their site.
setup.md tells the agent what needs to be shared and what the user should do next, in two or three sentences with the most important information.
This is an example of a response:
Your base is ready with [the pages you wrote]. Open this link, sign in with any account, and click Confirm: [claim link]
The next step in setup becomes clear.
Handling the edge cases #
Most setup guides only cover the happy path, so the agent freezes up when it gets blocked. Here are a few edge cases we saw agents hit.
- Claude Code's auto mode. When Claude Code's auto mode blocks installation, we give the agent a guide for how the user can unblock the agent, instead of the agent needing to infer it.
- Restarting MCP connections. New MCP config needs a fresh session to load, which ends the agent's session. We saw agents restart before setup was complete, so we added warnings that tell them when to restart.
- The rest of the edge cases. When the page itself is wrong, the agent can report it:
npx -y mint@latest feedback "setup step 2 failed: …" --client-id setup-report-001 --category bug. Reports go to our team and feed our loop.
Try it with your agent #
Paste this into any agent, hosted or local:
Read https://mintlify.com/docs/setup.md and set up Mintlify for me.
A hosted assistant hands you the connector steps. A coding agent does the install, verifies it, and tells you what to run after the restart. Either way, the next message you get should be short.
If your team's agents start from a repo, add one line to its root AGENTS.md:
To connect to Mintlify, read https://mintlify.com/docs/setup.md first.
The full page is at mintlify.com/docs/setup.
Frequently Asked Questions #
Does setup.md replace the Mintlify skill or mint instructions?
No. The skill carries authoring guidance and mint instructions covers task workflows once you're connected. setup.md covers the step before both: getting connected at all.
Can a person read it?
Yes. It's a normal docs page at mintlify.com/docs/setup. The .md link is the same content in plain Markdown, which is what agents fetch.
What if my agent isn't listed?
The page has a section for any MCP client that supports remote Streamable HTTP servers with OAuth, and the CLI path works from any agent with a shell.
Does the agent need my email?
No. The page tells the agent not to ask for it. You claim a new base or site by signing in with any account from the claim link, and the agent only prefills your email if it already knows your Mintlify account.
New to Mintlify? Sign up and let your agent take it from there.
More blog posts to read
We gave agents better instructions
We built a CLI command that gives coding agents current Mintlify guidance, and at first it changed nothing. One line in AGENTS.md, plus tighter guidance, took Claude Sonnet's pass rate on our hardest tasks from about one in five to every run.
November 10, 2026 Harkirat Chahal
Growth
Migrate to Mintlify with your agent
We turned what we learned from hundreds of migrations into mint migrate, so your agent can move your docs from 21 platforms, prove nothing went missing, and tell you what didn't carry over.
November 3, 2026 Sophia Barnes
Solutions Engineering