Connect Confluence to Atlan through Atlassian's Rovo MCP server so agents can read spaces and pages as context.
Connect Confluence as knowledge source Private Preview
You can connect Confluence so that Atlan agents read your spaces and pages. Atlan reads Confluence through Atlassian's Rovo MCP server, the official Atlassian endpoint for AI tools. Setup is one admin toggle, one scoped token, and three fields in Atlan.
Prerequisites
Before you begin, make sure you have:
- An Atlassian organization admin who can enable API token authentication for the Rovo MCP server and create service accounts
- An Atlassian service account with access to the Confluence spaces you want Atlan to read, see Choosing the account
- Permission to create integrations in Atlan. If you can't see Settings → Integrations, ask a workspace admin or raise a support request
- About 15 minutes
One person holding all three roles can complete this alone.
Three conditions, in this order
The connection works when all three are true, and order matters: the token must be created after the admin setting is enabled, because Atlassian doesn't apply the entitlement retroactively to tokens that already exist.
- Organization admin: API token authentication is enabled for the Rovo MCP server, and the Confluence read and search tools are allowed.
- Service account: a scoped API token exists with Confluence read and search access, created after the toggle was turned on.
- Atlan admin: site URL, service account email, and token are entered in Atlan.
Atlan doesn't crawl Confluence, doesn't use the classic Confluence REST API, and can't write to Confluence with this token. Every read is bounded by the permissions of the service account whose token you use.
Step 1: Enable API token authentication
- Go to admin.atlassian.com and sign in as an organization admin.
- From the organization switcher at the top of the left sidebar, select the organization that owns your Confluence site. If you administer more than one organization, the wrong one is often selected by default.
- Open Rovo → Rovo MCP server.
- Select the Authentication tab.
- Turn on Allow API token authentication.
Then select the Permissions tab and confirm that the Confluence Read and Search tools are allowed. If your organization has restricted them, the connection authenticates but Atlan can't read anything.
The Authentication tab also shows a second toggle, Allow enterprise managed authentication (preview), which routes MCP authorization through your IdP instead of individual user sign-ins. It's not required here.
Any API token created before you turn this toggle on keeps failing with a permission error, even once the setting is on. Always create a fresh token afterwards. This is the single most common reason a correct-looking setup fails.
Step 2: Create service account and token
The service account's Confluence permissions are the connection's permissions. See Choosing the account first, because that choice is your main access-control lever.
-
In admin.atlassian.com, with the same organization selected as in step 1, go to Directory → Service accounts and create a service account, for example
Atlan Confluence. -
Give it access to Confluence, and grant it view access only to the spaces you want Atlan to read.
-
Open the service account and create an API token.
-
Give it a recognizable name, for example
Atlan Confluence MCP (read). -
Set an expiry. See Rotation and expiry.
-
Under Rovo MCP, select exactly these two scopes, and no
write:scopes:read:confluence:agent-interfacesearch:confluence:agent-interface -
Create the token and copy it immediately. Atlassian shows the value once. If you lose it, delete that token and create another.
-
Note the service account's email address. It looks like
atlan-confluence@serviceaccount.atlassian.com, and you need it in step 3.
Step 3: Enter values in Atlan
- In your Atlan workspace, click Settings from the left sidebar.
- Under Team, click Integrations.
- Click the MCP filter, find Confluence, and click Connect.
- Fill in the three fields:
| Field | What to enter | Example |
|---|---|---|
| Confluence site URL | The Atlassian site the service account can access | your-company.atlassian.net |
| Atlassian account email | The service account's email from step 2 | atlan-confluence@serviceaccount.atlassian.com |
| Rovo MCP token | The scoped token from step 2 | ATATT... |
- Click Connect.
All three are required, each for a different reason:
- Token: the only credential Atlassian checks. The token alone authenticates.
- Site URL: every Confluence read needs your site's ID, and Atlan looks it up from this URL. A wrong site URL can still show Connected and then return nothing when agents run.
- Email: doesn't take part in authentication. It records which account's Confluence access agents inherit, so whoever rotates the token later knows which account holds it.
When you click Connect, Atlan checks that the token has the Confluence read and search scopes. Before each agent run, Atlan also runs a real Confluence search with the token and stops the run if the search is refused.
Choosing account
Scopes can only narrow access, never widen it. A scoped token is always bounded by the Confluence permissions of the service account that holds it, so Atlan can never read a page that account can't already read. That makes the service account's space access your access-control lever.
Use a dedicated Atlassian service account, not someone's own account. You get space-level control, the connection survives employee departures, and it can be revoked centrally without touching anyone's own access.
Atlassian includes five service accounts per organization. More require an Atlassian Guard subscription.
The scope set in step 2 contains no write scopes, so Atlan can't create, edit, or delete Confluence pages or comments. Rovo MCP doesn't show write tools to a token without write scopes. The token also carries no Jira, Bitbucket, or Jira Service Management scopes: it reaches Confluence only.
Rotation, expiry, and revocation
- Expiry. Match your own policy. With no policy in place, 365 days is a reasonable default, plus a calendar reminder two weeks ahead.
- Rotation. Create the new token first, update it in Atlan, confirm the connection succeeds, then delete the old one. Deleting a token stops the connection immediately.
- Revocation. Delete the token on the service account in admin.atlassian.com to cut Atlan's access. Turning off the organization-level Allow API token authentication toggle revokes all Rovo MCP API token access at once.
Validate results
After entering the values, confirm the connection works before you rely on it:
- The Confluence card in Settings shows Connected, along with when the credentials were last updated. Atlan verifies the credentials before storing them, so a successful connection means the token authenticated and has the Confluence read and search scopes.
- Confluence appears as a selectable source when you create or edit an agent.
- Run a sample run on an agent that uses Confluence. A sample publishes nothing and returns proposed items with citations, so cited results confirm the agent can read your spaces.
A connection can authenticate and still read nothing if the token's account has no access to the spaces you expect, or if the site URL is wrong, so the sample run is the check that matters. See Troubleshooting.
Troubleshooting
Each prerequisite fails with a different error, so read the error text and match it here rather than repeatedly recreating the token.
| What you see | Cause | Fix |
|---|---|---|
| "You don't have permission to connect via API token. Please ask your organization admin for access." | The organization setting is off, or the token predates it being turned on | Confirm step 1, then create a new token |
| "Insufficient scopes" | The token is missing one of the two scopes in step 2 | Recreate the token with both read:confluence:agent-interface and search:confluence:agent-interface |
| "That credential reached confluence but exposed no … tools" when you click Connect | The token is missing the agent-interface scopes | Create a new token with both scopes in step 2 |
| "Atlassian rejected that API token" | The token has expired, been revoked, or was copied incorrectly | Create a new token and reconnect |
| "Could not read the Confluence site id from …" when a run starts | The Confluence site URL isn't a valid Atlassian site | Enter the site as your-company.atlassian.net and reconnect |
| "A test search was refused" when a run starts | The token lacks the agent-interface scopes, or was issued for a different site than the site URL | Check that the site URL matches the service account's site, then recreate the token with both scopes |
| Connects, but returns no content | The service account has no access to those spaces, or the Confluence tools are disallowed in the Rovo MCP Permissions tab | Check the service account's space permissions, then step 1 |
| Intermittent empty search results | Atlassian rate-limits bursts of new sessions | Transient, retry. Persistent emptiness is a permissions issue, not rate limiting |
Frequently asked questions
Can this be limited to specific spaces?
Yes, through the service account's Confluence permissions. Grant it access only to the spaces you want in scope. There is no space filter on the token itself.
Do Rovo licences need to be purchased?
Rovo MCP is the Atlassian endpoint used for the connection. If the Rovo section is missing from admin.atlassian.com, check with your Atlassian account team.
Can OAuth be used instead of token?
OAuth 2.1 is Atlassian's default for interactive AI tools, but it needs a human to sign in per session. A service account API token is the supported path for a service integration that runs unattended, including scheduled agent runs.
Is one token enough for multiple Atlassian sites?
The token isn't bound to a site, but each Atlan connection points at one site URL. Set up one connection per Confluence site.
Need help
If you need assistance after reviewing this page, contact Atlan support.
See also
- Knowledge sources: how connections and access work
- Create an agent from a template: use this source in an agent