pages, spaces, search, content, comments, labels, attachments, versions), each driven by an action argument, and runs in the tenant app-instance context (it resolves the installing workspace’s own credentials and gates which agents may call it). Authentication is per-user and supports several modes:
- Per-user OAuth2 with central client (
oauthCentral, recommended): one Atlassian 3LO OAuth app is registered once by the platform maintainer; every end user signs in with their own Atlassian account. Nothing to register per tenant: each workspace just installs the app and clicks Connect. - Per-user OAuth2 with tenant client (
oauth): paste your own Atlassian OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (PKCE authorization-code, 3LO). - API token (HTTP Basic) (
apiToken): an Atlassian account email + API token + your*.atlassian.netsite. A single shared service identity, no interactive sign-in. - Direct access token (
accessToken): a caller-managed Atlassian access token, used as-is with no exchange.
Pages & spaces
Search & hierarchy
Per-user Atlassian OAuth
Who is this for?
This connector is used by three different roles. Jump to the section that matches yours; each one is self-contained.Agent builder
Platform admin
Workspace builder
Prerequisites (Atlassian side)
- An Atlassian Confluence Cloud site (
https://yoursite.atlassian.net) and an account with permission on the spaces you intend to use. - For the OAuth modes: an OAuth 2.0 (3LO) app registered in the Atlassian Developer Console, with the Confluence API added and the granular scopes below granted. For the
apiTokenmode instead: an Atlassian account email + an API token generated at Atlassian API Tokens. - The base URL is resolved automatically: OAuth modes call
https://api.atlassian.com/ex/confluence/{cloudId}(thecloudIdis discovered from the granted site); theapiTokenmode callshttps://{site}.atlassian.netdirectly.
*:confluence-content.all scopes only authorize the legacy v1 API). The complete granular scope set requested by default, covering all 20 operations, is:
read:content-details:confluence authorizes the v1 CQL search (search tool); read:hierarchical-content:confluence covers children / descendants (content tool); and read:content.metadata:confluence is required for page ancestors. Drop them and the corresponding operations return 403.Platform admin (Governance): one-time platform setup
Platform admin (Governance): one-time platform setup
1. Configure the connector
Register the OAuth 2.0 (3LO) app at Atlassian
https://api.studio.prisme.ai/v2/workspaces/slug:confluence-next/webhooks/oauthCallback on production; <api-url> is the production API URL. Copy the exact URI from the connector’s configuration app, which renders it for you.) Then under Permissions, add the Confluence API and enable the granular scopes listed in Prerequisites. Note the Client ID and Secret from Settings.Confirm the scopes are granular, not classic
*:confluence scopes; the classic Confluence scopes (e.g. read:confluence-content.all) authorize the legacy v1 API and will not appear in the granular list. Enable the full granular set from Prerequisites; partial sets cause 403 on the missing operations.Enter the credentials through the configuration app
confluence-next workspace and launch its Configuration app: <studio>/apps/confluence-next (e.g. https://studio.prisme.ai/apps/confluence-next), also linked as Configuration app on the installed instance. Switch to the maintainer view and follow the in-app instructions to paste the Client ID, Client Secret and the Scopes; the app stores them in the core workspace’s secrets for you. Do not edit Studio’s raw Secrets by hand. These credentials stay in the confluence-next workspace and are never exposed to tenants or end users; token exchange is proxied through the core centralTokenExchange webhook so the client secret never leaves the core workspace.Tell workspaces to use the central client
oauthCentral in the connector configuration app (no client id/secret to enter on their side). Their users then just click Connect.2. Declare the capability in AI Governance
Generic connectors (broad tool surfaces meant to be shared across many agents, like Confluence) are best exposed as a named capability in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.Open AI Governance > Capabilities
Point it at the MCP endpoint
agent_id in the scope is what lets the connector identify and authorize the calling agent.Make it available to agent builders
Smoke-test
oauthCentral, trigger any tool. The user is prompted to connect once (Atlassian sign-in); subsequent calls reuse the stored token transparently and refresh it automatically.- Agent builder (Agent Creator)
- Workspace builder (DSUL)
Agent builder
Goal: let an agent you build in Agent Creator read and act on Confluence through MCP tools.agent_id that Agent Creator injects through the capability Scope, and that agent must appear in the connector’s authorized-agents allowlist (managed in the configuration app). The Atlassian token itself is resolved server-side from the configured auth mode.There are two ways to wire it up. Pick based on how much isolation you need.Option A: Enable the shared capability from the catalog
The fastest path: a Platform admin has already published a Confluence capability (see the Platform admin setup accordion above, §2), so you just pick it from the catalog.Open your agent in Agent Creator
Add the Confluence capability
context_id,agent_id,user_id) are already wired by the admin: nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side.Connect an Atlassian account (OAuth modes)
connect_url. The apiToken and accessToken modes need no per-user sign-in.Option B: Run it from your own workspace (recommended)
For production agents, install the connector in your own workspace and point the agent at that workspace’s MCP endpoint.Install and configure the connector in your workspace
Allowlist your agent
Add the MCP capability to your agent
agent_id is what lets the connector identify and authorize your agent; without it, every call is rejected with an explicit “agent could not be identified” message. This Scope is separate from the Atlassian OAuth scopes.Connect an Atlassian account (OAuth modes)
Brief the agent in its system prompt
Whichever option you pick, wiring the capability is not enough: the agent must know the MCP exists and when to use it. Copy-pasteable starter:agent_id.write:page:confluence, delete:page:confluence, write:comment:confluence, write:label:confluence.) With central OAuth (oauthCentral) you do not create your own Atlassian client; keep oauthCentral and just enter the read-only scopes; your tenant scope overrides the platform default (the central app must expose those read scopes). Write calls are then rejected by Atlassian with 403. Note this is set at the workspace level: a workspace editor can widen it again; a provider-side restriction (a read-only Atlassian account/space permission) is the only hard guarantee. For the apiToken mode, restrict at the provider instead by backing the connection with a Confluence account that has read-only space permissions.Available Tools
Each tool takes anaction argument selecting the concrete operation, plus the per-action parameters.Output Formats
Every tool accepts anoutputFormat argument that controls the MCP response shape:verbose(default): human-readable text optimized for LLM consumptionstructured: machine-readable JSON instructuredContentboth: both the text and the structured content
Tool Details
search
pages
get returns page metadata without the body; use getBody (or get with bodyFormat) to read the content. Updating a page is optimistic-locked: pass version: { number } one above the page’s current version, or Confluence returns a conflict.content
comments
Error Handling
Common Issues
“This agent is not authorized to use this connector”: The calling agent is not in the allowlist. Open the configuration app → Authorized agents → tick this agent (or enable Allow all agents) and Save. “The calling agent could not be identified”: The MCP capability Scope does not declareagent_id, so Agent Creator never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability, then allow the agent in the config app.
“Confluence is not connected for this user”: No per-user OAuth token. Open the configuration app (OAuth mode) and click Connect, or use the agent’s connect flow.
“token refresh failed … must reconnect”: The stored refresh token was revoked or expired (Atlassian invalidated it). The connection is dropped automatically; the user must reconnect from the config app.
“OAuth is not configured”: Neither a tenant Atlassian client nor the central platform client is available. Set the OAuth client ID/secret in the config app, or ask the platform maintainer to provision the central OAuth client.
403 on search, hierarchy or ancestors despite read access: The Confluence v2 API needs granular scopes the classic set does not cover: read:content-details:confluence (CQL search), read:hierarchical-content:confluence (children / descendants) and read:content.metadata:confluence (ancestors). Add the missing scope to the connector Scopes field and reconnect. Confluence v2 will not work on classic scopes.
External Resources
Confluence Cloud REST API v2
Confluence CQL search (v1)
search tool.