What works in practice using Confluence as the knowledge base for an external AI agent via MCP?

[Pricilla]

Details:

I use Claude Code (CLI) with MCP servers as a working agent for my business operations, mostly finance and accounting preparation. And other agents for ecommerce development. Its knowledge base today is Notion plus local files, and that split is the actual problem: the rules it needs live in too many places, so it doesn't reliably pick the right one for the task in front of it.

I want Confluence to be the single place it reads procedures from.

What I've done so far:

- Running Claude Code with the Notion MCP server connected; that's the setup I'm trying to replace
- Identified the official Atlassian remote MCP server and its current endpoint, and confirmed OAuth 2.1 discovers the accessible Cloud sites, so no site URL is needed up front
- Plan is to connect read-only first and add write access later, behind a reversible wrapper. I don't want an agent making unlogged changes to a knowledge base
- Not connected yet; I'd rather get the page structure right before pointing an agent at it

Where I need input:

- Is anyone running the Atlassian MCP server with Confluence as an agent's knowledge base? How reliable is retrieval in practice?
- How do you structure spaces and pages so the agent finds the right page instead of a plausible neighbour? One page per procedure, labels, page properties?
- Where's the sensible line between Rovo and an external agent over MCP? Are people using both for different jobs?
- Does anyone deliberately run it read-only, and how do you handle the read / write / search permission groups?

Interested in real setups rather than the marketing version, including what didn't work.

[Sami Shaik]

Hello @Pricilla , @Ajay _view26_ has covered structure and the Rovo split well, so let me take your fourth question, the read-only and permission groups one, since nobody has touched it and it is the piece that decides whether this is safe to run unattended.

The core mental model: the MCP connection never acts as "your site." It acts as one specific identity, and the server enforces that identity's Confluence permissions on every request. So "read only" is something you build at two levels, and they are not equally strong.

Level 1, the identity (the real guarantee). With the OAuth 2.1 flow you have already tested, the connection acts as you, with everything your account can see and do. That is fine for evaluation, but for a standing finance or ecommerce agent it means the agent's reach silently equals yours. The stronger pattern for your end state: a dedicated service account per agent, given view permission only on the knowledge base spaces it serves, connected through API token authentication, which is the mode Atlassian provides for exactly this (non-interactive agents and backend services; your org admin has to enable it). Because permissions are enforced server side, an account that only has view rights physically cannot write, whatever the client asks for. That is your reversible wrapper, done at the source: adding write later is a permission change on one account, not a re-architecture.

Level 2, the tools (the guardrail). The read / write / search grouping you mentioned is real: the MCP server's tools are organized by product and by intent (read, write, or search). In Claude Code you can restrict which tools the agent is allowed to call, so allowlisting only the read and search tools gives you a client-side read-only mode today, before any admin change. Treat this as a guardrail rather than the guarantee, since it lives in client configuration; the identity's permissions are what the server actually enforces.

My recommended sequence for you:

1. Evaluate now over OAuth as yourself, with only read and search tools allowlisted in Claude Code.
2. When it proves out, move each standing agent to its own service account with view-only space permissions over API token auth.
3. One account per agent also means the audit log tells you exactly which agent read what, and you can revoke one without touching the others.

Atlassian's own guidance for MCP connections is least privilege plus regular audit log review, and for an agent handling finance procedures I would make that review a scheduled task, not an intention.

One addition to Ajay's Rovo split that matters for permissions specifically: Rovo inherits each asking user's permissions automatically, per person, per question. Your external agent runs as one fixed identity for everyone and everything it serves. That is the deeper reason to keep its account minimal: an over-permissioned agent account can carry information across boundaries that Rovo would respect by default.

Good luck with the consolidation. Sorting the identity model out before pointing an agent at the knowledge base is the right order, and you are already doing it.

[Ajay _view26_]

Hi @Pricilla 

Welcome to the community..Below is my take..

1. Reliability of retrieval via the MCP server in practice.

Short answer: it works, and the retrieval is more reliable than what I had with Notion. The official Atlassian Rovo MCP server handles the OAuth 2.1 handshake cleanly — you authenticate once, it discovers your accessible Cloud sites, and from there the agent reads Confluence through the Teamwork Graph (Atlassian's knowledge model that maps relationships between content, people, and work). Retrieval is permission-filtered automatically: every request the server handles goes through a two-step check — is this external tool an authorised domain, and does the requesting user have access to this content? If either answer is no, nothing comes back. That's not a setting you configure, it's baked in.

Where reliability actually breaks down isn't the connection layer — it's content quality. Pages loaded with macros (Jira issue tables, roadmap embeds, Loom blocks, status macros) come through as noisy HTML that eats tokens and confuses retrieval. My biggest single improvement was stripping procedure pages down to plain text, headings, and simple tables.

2. Page structure — how to make the agent find the right page.

 One space per major domain (e.g., "Finance Operations"), not one giant space for everything. Within each space, one parent page per process area (e.g., "Accounts Receivable Procedures"), with child pages for each individual procedure. That gives you a two-level hierarchy the agent can navigate predictably.

Page properties macros are tempting but don't bother for agent consumption. They render as structured HTML that looks useful to humans but is just noise to the agent. Put your metadata in labels and in a consistent "Applies to" section at the top of each page in plain text instead.

3. Rovo vs. external agent over MCP — where each fits.

I use both, and they serve genuinely different jobs. Here's how I think about the split:

Rovo (Search, Chat, Agents built in Rovo Studio) is best for work that happens inside Atlassian. If someone on my team needs to search across Jira and Confluence at once, summarise a page, or run a simple agent that transitions issues or posts comments — that's Rovo's lane. It's embedded in the tools, it inherits all permissions automatically, and the agents built in Studio are scoped by tools the admin assigns (Atlassian recommends fewer than five tools per agent — basically least-privilege by design). 

The external agent over MCP (Claude Code in my case) is better for work that spans systems or requires complex reasoning the Studio agent builder can't handle. 

The governance model supports both coexisting. Rovo's admin controls (Admin Hub → Rovo) cover the internal surfaces. The MCP server settings separately control which external clients can connect and how they authenticate. 

Also you may refer to https://community.atlassian.com/forums/Atlassian-AI-Rovo-articles/Governing-Rovo-The-Permission-Model-and-Control-Levers-in-One/ba-p/3276674#M2501 on the Rovo permission model and configurations