What is a role-aware MCP server for documentation?

Most documentation tools now claim to "have MCP." But there's a quiet, important difference between an MCP server that dumps your whole docs set to any connected agent and one that respects who is asking. The second kind — a role-aware MCP server — is what makes AI access safe on private, client-facing documentation.

What MCP is, in one paragraph

The Model Context Protocol (MCP) is an open standard that lets AI clients — Claude Code, Cursor, Claude Desktop, ChatGPT, and others — connect to external tools and data sources. An MCP server for documentation exposes your docs so an agent can search them and answer questions grounded in your actual content, instead of guessing.

Why "role-aware" is the part that matters

Documentation isn't flat. An admin should see everything. A client should see only their project. A contractor shouldn't see internal runbooks. A role-aware MCP server enforces exactly that: each connection inherits the connecting user's role and project scope, and results are filtered accordingly.

Here's the same question, two accounts, one server:

Admin agent  → "Find the deployment runbook"  → returns runbook.md + internal notes
Client agent → "Find the deployment runbook"  → runbook is internal → returns nothing

The agent didn't change. The permissions did. That's role-awareness.

How it works under the hood

1. The agent authenticates as a user via OAuth 2.1 + PKCE — not as an anonymous app.
2. Every search/fetch is filtered by that user's role (admin / commenter / viewer) and project scope.
3. Ignored files are never indexed. With Miradorly, anything matched by .docignore is genuinely absent from the index — not hidden in the UI, but never searchable or returnable over MCP.
4. Read-only by design. The agent can read documents; it cannot mutate or overwrite them.

# .docignore — excluded from rendering, search, and MCP for every role
CLAUDE.md
**/secrets/**
drafts/
*.internal.md

Why most doc-tool MCPs fall short here

Public-only MCP can't serve private client docs at all. Notion's MCP blocks the guest accounts that clients and contractors use. A role-aware MCP over private docs is the model that actually fits agency and client work.

When you need a role-aware MCP

You need one if any of these are true:

• You share docs with clients or contractors and want their AI agents to query them.
• Your repo mixes internal and external docs that must not leak to the wrong reader.
• You want AI access to private documentation without making it public.

If your docs are fully public and single-audience, a simpler public MCP is enough. The moment access control matters, role-awareness is the requirement — not a nice-to-have.

How to set one up

With Miradorly, the MCP server is included and inherits the same permission model as the portal and comments — one access system, three surfaces. Connect any MCP-capable client:

claude mcp add miradorly https://mcp.miradorly.com/<your-workspace>

From there, each user's agent sees exactly what their account can see. Nothing more.