We built one page to help AI agents set up Mintlify

Mintlify published setup.md, a single documentation page that tells AI agents how to install and configure Mintlify, after observing agents such as Claude.ai and Claude Code fetch multiple docs pages, run wrong commands, and return long instructions instead of completing setup. The page opens by asking the agent whether it can edit files on the machine, then directs hosted assistants like Claude.ai and ChatGPT to connector-based setup and coding agents like Claude Code, Codex, Cursor, Antigravity and Grok Build to a one-command install, `npx -y mint@latest agent setup --global --agent claude-code`, which installs the Mintlify skill and adds the mintlify-admin MCP server to the agent's config. Mintlify said the approach applies its earlier llms.txt benchmark finding, where a single link to llms.txt eliminated most agent 404s, and its install.md proposal for LLM-executable installation to its own product.

All articles https://www.mintlify.com/blog We built one page to help AI agents set up Mintlify 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 https://www.mintlify.com/docs/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 why-agents-kept-getting-setup-wrong Setup spans the Mintlify CLI https://www.mintlify.com/docs/cli , Admin MCP server https://www.mintlify.com/docs/ai/mintlify-mcp , 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 https://www.mintlify.com/blog/llms-txt-agent-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 https://www.mintlify.com/blog/install-md-standard-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 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 https://www.mintlify.com/blog/skill-md 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 https://www.mintlify.com/blog/introducing-mintlify-base and gets created with mint deploy --base , no account needed until the claim. A public docs site goes through mint deploy https://www.mintlify.com/blog/mint-deploy . The agent never has to work out which product the user meant from context, because it asked. Include user-guided prompts 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 https://www.mintlify.com/docs/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 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 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 https://www.mintlify.com/docs/setup . Frequently Asked Questions 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 https://www.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 https://app.mintlify.com/signup and let your agent take it from there. More blog posts to read EngineeringHC https://www.mintlify.com/blog/mint-instructions 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 AnnouncementsSB https://www.mintlify.com/blog/mint-migrate 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