Miradorly vs GitBook: which fits an agency sharing docs with clients?

I run a software agency. We write project docs in markdown, edit them in Cursor and Claude Code, and commit them to git like everything else. The recurring problem was never writing the docs — it was sharing them with a client who doesn't have (and shouldn't have) repo access. GitBook was the obvious answer for years. Then we did the math and the migration, and changed our minds. Here's the honest comparison.

The core difference: platform vs overlay

GitBook is a documentation platform. You author content inside GitBook's editor, and it becomes the source of truth. There's a git-sync feature, but in practice the workflow centers on GitBook's WYSIWYG — your team writes there, not in the IDE.

Miradorly is an overlay. The source of truth stays in your GitHub or GitLab repo. Your team keeps writing .md in whatever editor they already use; every commit renders live in Miradorly as a clean portal. Nothing migrates.

That single architectural choice drives every other difference below — pricing, who can read the docs, and how AI agents query them.

Editor lock-in

With GitBook, the practical expectation is that authoring happens in GitBook. If your team has already standardized on Cursor or Claude Code with markdown in the repo, you're now maintaining docs in two mental models — or you abandon the IDE workflow you adopted on purpose.

With Miradorly there is no second editor. You write where you write today. This matters most for teams who moved to docs-as-code deliberately and don't want to give it up to get a nicer reader experience.

Pricing, in real numbers

GitBook's 2025 repricing is what pushed a lot of small teams to look elsewhere — there's a well-known thread of teams leaving over it. The flat model is the point of Miradorly: you don't get punished for inviting one more client.

Who can read the docs

This is where the overlay model pays off for agencies. In Miradorly, anyone you invite — a client PM, a designer, HR, sales, leadership — signs in with email or Google, sees only the projects they're assigned, and comments per section. They never see your repo, and you never run a GitHub access review for a non-technical stakeholder.

GitBook handles readers and comments inside its own workspace and seat model, which is fine — but it's another set of accounts and seats to manage, and the cost scales with people.

The MCP server: public vs private

Both tools now have an MCP story, but they're not the same:

• GitBook's MCP targets your published (public) documentation.
• Miradorly's MCP runs on private docs, inherits each user's role, is secured with OAuth 2.1 + PKCE, and is read-only by design — an agent can read, never overwrite.

Crucially, Miradorly respects .docignore: files like CLAUDE.md, secrets, and drafts are never indexed and never returned over MCP, regardless of who asks.

# .docignore — never rendered, never indexed, never returned over MCP
CLAUDE.md
**/secrets/**
drafts/
*.internal.md

If your use case is "let my client's AI agent answer questions from the docs they're allowed to see, without leaking the internal ones," that's specifically what role-aware MCP over private docs is for.

When GitBook is the better choice

I'm not going to pretend Miradorly wins every scenario. Choose GitBook if:

• You want a full authoring suite with WYSIWYG and don't already live in an IDE.
• You're building a large public knowledge base and want GitBook's published-site features.
• Your team isn't on docs-as-code and has no intention of moving there.

Choose Miradorly if:

• Your docs already live in a git repo and your team writes them in Cursor / Claude Code.
• You share docs with clients or non-technical stakeholders who shouldn't have repo access.
• You want a role-aware MCP that works on private docs.
• You want flat, predictable pricing that doesn't climb with every invited seat.

How to decide in five minutes

Ask one question: where does your team actually write documentation today? If the answer is "in our repo, in our editor," an overlay keeps that workflow and adds the sharing layer on top. If the answer is "we don't really have a workflow yet," a platform like GitBook gives you one out of the box. Both are valid — they're just solving the problem from opposite ends.