Skip to main content

Confluence MCP server

Confluence is Atlassian's collaborative wiki platform where teams create, organize, and share documentation, meeting notes, and project knowledge. Through the AI Gateway integration, an AI agent can read and write pages, manage spaces, search content using Confluence Query Language (CQL), and handle comments and attachments. Technical writers, project managers, and teams maintaining large documentation repositories will get the most from this integration.

Setting up an MCP server

This article covers the standard steps for creating an MCP server in AI Gateway and connecting it to an AI client. The steps are the same for every integration — application-specific details (API credentials, OAuth endpoints, and scopes) are covered in the individual application pages.

Before you begin​

You'll need:

  • Access to AI Gateway with permission to create MCP servers
  • API credentials for the application you're connecting (see the relevant application page for what to collect)

Create an MCP server​

Find the API in the catalog​

  1. Sign in to AI Gateway and select MCP Servers from the left navigation.
  2. Select New MCP Server.
  3. Search for the application you want to connect, then select it from the catalog.

Configure the server​

  1. Enter a Name for your server — something descriptive that identifies both the application and its purpose (for example, "Zendesk Support — Prod").
  2. Enter a Description so your team knows what the server is for.
  3. Set the Timeout value. 30 seconds works for most APIs; increase to 60 seconds for APIs that return large payloads.
  4. Toggle Production mode on if this server will be used in a live workflow.
  5. Select Next.

Configure authentication​

Enter the authentication details for the application. This varies by service — see the Authentication section of the relevant application page for the specific credentials, OAuth URLs, and scopes to use.

Configure security​

  1. Set any Rate limits appropriate for your use case and the API's own limits.
  2. Enable Logging if you want AI Gateway to record requests and responses for auditing.
  3. Select Next.

Deploy​

Review the summary, then select Deploy. AI Gateway provisions the server and provides a server URL you'll use when configuring your AI client.

Connect to an AI client​

Once your server is deployed, you'll need to add it to the AI client your team uses. Select your client for setup instructions:

Tips​

  • You can create multiple MCP servers for the same application — for example, a read-only server for reporting agents and a read-write server for automation workflows.
  • If you're unsure which OAuth scopes to request, start with the minimum read-only set and add write scopes only when needed. Most application pages include scope recommendations.
  • You can edit a server's name, description, timeout, and security settings after deployment without redeploying.

When to use this integration​

If you want to…Relevant tools
Keep documentation up to date automaticallyCreate page, update page
Search and extract information across spacesSearch (CQL), list pages
Manage team wikis and project spacesCreate space, update space, space permissions
Handle comments and review workflowsCreate comment, list comments, delete comment

Authentication​

Confluence uses OAuth 2.0 via the Atlassian developer console. Register an OAuth 2.0 integration, set the callback URL to the value shown in AI Gateway, and select the scopes appropriate for your use case. Common scope combinations:

  • Read-only access: read:page:confluence, read:space:confluence, read:attachment:confluence, read:comment:confluence
  • Documentation management: Add write:page:confluence, write:attachment:confluence, write:comment:confluence
  • Space administration: Also add write:space:confluence

Available tools​

The integration exposes tools across pages, spaces, attachments, comments, and content search. Select the endpoints you need when configuring the MCP server — you don't need to enable all of them.

Pages​

ToolDescription
Create pageCreate a new page or blog post in a space
Get pageRetrieve the content and metadata of a page
Update pageEdit the title, body, or properties of a page
Delete pageRemove a page from a space
List pagesReturn pages in a space, optionally filtered
Get page versionsView the revision history of a page
Get page childrenList child pages under a given page
Get page ancestorsReturn the parent hierarchy above a page

Spaces​

ToolDescription
Create spaceSet up a new Confluence space
Get spaceRetrieve details and settings for a space
Update spaceModify space metadata and settings
Delete spaceRemove a space and its content
List spacesReturn all accessible spaces
Get space permissionsView current permission settings for a space

Attachments​

ToolDescription
Upload attachmentAttach a file to a page
Get attachmentRetrieve an attachment and its metadata
List attachmentsReturn all attachments on a page
Delete attachmentRemove a file from a page

Comments​

ToolDescription
Create commentAdd a footer or inline comment to a page
Get commentRetrieve a specific comment
Update commentEdit an existing comment
Delete commentRemove a comment from a page
List commentsReturn all comments on a page

Search and labels​

ToolDescription
Search (CQL)Query content across spaces using Confluence Query Language
List labelsReturn all labels applied to a page
Add labelAttach a label to a page
Remove labelRemove a label from a page

Tips​

Start with the narrowest set of OAuth scopes that covers your use case. Read-only scopes are sufficient for search and documentation analysis workflows; write scopes are needed only when creating or modifying content.

For bulk operations, build in delays between calls or use the expand parameter to retrieve related data in fewer requests. Atlassian enforces a rate limit of 10 requests per second for Confluence Cloud.

  • Space Analytics
    • "Show space activity over time"
    • "Identify inactive spaces"
    • "Track space growth and usage"
    • "Generate space health reports"

Reporting & Analytics​

  • Content Analytics

    • "Generate monthly documentation metrics"
    • "Track page view trends by category"
    • "Analyze engagement with knowledge base"
    • "Measure documentation completeness"

  • Team Productivity

    • "Show contribution statistics by team member"
    • "Track documentation velocity"
    • "Identify knowledge sharing patterns"
    • "Measure collaboration effectiveness"

  • Quality Metrics

    • "Find outdated pages needing updates"
    • "Check documentation coverage by topic"
    • "Analyze content freshness"
    • "Track template usage"

Automation & Integration​

  • Content Automation

    • "Auto-generate release notes from Jira"
    • "Create weekly status reports from data"
    • "Build documentation from code comments"
    • "Sync content with external systems"

  • Workflow Integration

    • "Create Confluence pages from Slack discussions"
    • "Link Jira issues to documentation"
    • "Update pages when code changes"
    • "Trigger actions on page updates"

  • Template Management

    • "Create dynamic templates with variables"
    • "Apply templates based on page type"
    • "Update all pages using specific template"
    • "Track template effectiveness"

Prerequisites​

  • Access to Cequence AI Gateway
  • Confluence Cloud or Data Center instance
  • Confluence administrator access
  • Atlassian account for OAuth setup

Step 1: Create Atlassian OAuth App​

Before setting up the MCP server, you need to create an OAuth app in Atlassian.

1.1 Access Atlassian Developer Console​

  1. Navigate to developer.atlassian.com
  2. Sign in with your Atlassian account
  3. Click Create OAuth 2.0 integration

1.2 Configure OAuth App​

  1. Set basic information:

    • App name: "AI Gateway Confluence MCP"
    • App description: "MCP server for Confluence integration"
    • Company: Your organization name

  2. Configure OAuth 2.0:

    • Callback URL: 
      https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

  3. Configure Permissions:

    • Go to Permissions tab
    • Add Confluence API scopes (see Available Scopes section)

1.3 Get OAuth Credentials​

  1. Go to Settings tab
  2. Note down:
    • Client ID
    • Client Secret (click to reveal)

1.4 Configure App Details​

  1. Add App logo (optional)
  2. Set Privacy policy URL
  3. Set Terms of service URL
  4. Configure Data residency if needed

Step 2: Access AI Gateway Apps​

  1. Log in to your Cequence AI Gateway dashboard
  2. Navigate to Apps in the left sidebar
  3. You'll see the list of available third-party applications

Step 3: Find and Select Confluence API​

  1. In the Apps section, browse through the Third-party category
  2. Look for Confluence or use the search function
  3. Click on the Confluence API card to view details

The Confluence API card shows:

  • Number of available endpoints
  • Integration capabilities
  • Quick description of functionality

Step 4: Create MCP Server​

  1. Click the Create MCP Server button on the Confluence API card
  2. You'll be redirected to the MCP Server creation wizard

Step 5: Configure API Endpoints​

In the App Configuration step:

  1. Base URL is pre-filled: https://api.atlassian.com/ex/confluence/{cloudid}/wiki/api/v2
  2. Select API endpoints to expose to your MCP server based on your needs
  3. Click Next to proceed

Step 6: MCP Server Basic Setup​

Configure your MCP server details:

  1. MCP Server Name: Enter a descriptive name

    • Example: "Confluence Knowledge Base"
    • This name will identify your server in the dashboard

  2. Description (Optional): Add details about the server's purpose

    • Example: "Automated documentation management and knowledge base operations"

  3. Production Mode: Toggle based on your needs

    • ON for production environments
    • OFF for development/testing

  4. Click Next to continue

Step 7: Configure Authentication​

This is where you'll use your Atlassian OAuth credentials:

  1. Authentication Type: Select OAuth 2.0

  2. Fill in the OAuth configuration:

    • Authorization URL: 
      https://auth.atlassian.com/authorize
    • Token URL: 
      https://auth.atlassian.com/oauth/token
    • Client ID: Paste from Atlassian developer console
    • Client Secret: Paste from Atlassian developer console
    • Redirect URI: 
      https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

  3. Scopes: Paste the full scope string from the next section.

  4. Click Save Authentication.

Step 7.1: Authorize via AI Gateway​

After saving OAuth settings, complete the runtime authorization handshake in Gateway:

  1. Open your deployed Confluence MCP server in the AI Gateway dashboard.
  2. Click Authorize, Connect Account, or Test Connection (label may vary by UI version).
  3. Sign in to Atlassian and choose the Confluence site to grant access.
  4. Approve the requested scopes.
  5. Return to Gateway and confirm status is Connected.

If authorization fails, verify:

  • Redirect URI is exactly https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
  • Authorization URL is https://auth.atlassian.com/authorize
  • Token URL is https://auth.atlassian.com/oauth/token
  • The app in Atlassian Developer Console has all scopes below enabled
  • You re-authorized after adding new scopes

Available Confluence OAuth Scopes​

Atlassian offers classic scopes (broad umbrellas such as read:confluence-content.all, write:confluence-content) and fine-grained scopes (resource-specific such as read:page:confluence, write:content:confluence). For Confluence Cloud REST API v2 and the Cequence Confluence MCP OpenAPI, operations are overwhelmingly declared with granular scopes only.

Scopes that are not redundant (cross-cutting)​

ScopeRole
offline_accessRefresh tokens (OAuth)
read:meAtlassian account / identity
details:confluenceConfluence product “details” APIs where documented
search:confluenceConfluence search / Rovo-style product access where required
manage:confluence-configurationAdmin-style configuration APIs (only if you expose those tools)
read:content-details:confluenceRich content / expansion-style reads on v2
read:content.metadata:confluenceContent metadata reads
read:user:confluenceUser resolution / lookup (granular)
readonly:content.attachment:confluenceNarrow attachment read variant when required
read:label:confluenceSite-wide label reads / discovery APIs
write:label:confluenceLabel write operations where Atlassian or Gateway requires this scope (use with write:page:confluence for addPageLabels if you see scope errors)

Recommended: full access, granular-only (Confluence v2 / MCP)​

Use this as the primary copy-paste string for “full” MCP parity without classic umbrellas:

offline_access details:confluence search:confluence manage:confluence-configuration read:me read:user:confluence read:content-details:confluence read:content.metadata:confluence read:page:confluence read:space:confluence read:attachment:confluence read:comment:confluence read:label:confluence write:label:confluence read:custom-content:confluence read:task:confluence write:task:confluence read:whiteboard:confluence read:database:confluence read:embed:confluence read:folder:confluence read:hierarchical-content:confluence readonly:content.attachment:confluence write:space:confluence write:page:confluence write:attachment:confluence write:content:confluence write:comment:confluence write:custom-content:confluence write:whiteboard:confluence write:database:confluence write:embed:confluence write:folder:confluence write:app-data:confluence delete:custom-content:confluence delete:page:confluence delete:comment:confluence delete:whiteboard:confluence delete:database:confluence delete:embed:confluence delete:folder:confluence

Optional: classic add-ons (belt-and-suspenders)​

Only if you still call legacy v1 endpoints, older marketplace docs, or a component that explicitly requires classic names:

read:confluence-content.all read:confluence-content.summary read:confluence-content.permission read:confluence-space.summary read:confluence-user read:confluence-groups read:confluence-props write:confluence-content write:confluence-space write:confluence-file write:confluence-props write:confluence-groups

Append them to the granular string only when needed; they overlap granular coverage for normal v2 usage.

Notes​

  • Keep scopes space-separated when entering them in OAuth forms that expect a single string.
  • If scopes are entered as a list in UI fields, add one scope per line using the same values.
  • addPageLabels: the OpenAPI spec lists write:page:confluence; also request write:label:confluence so the token satisfies Gateway or Atlassian label-write checks. For reading labels, include read:label:confluence and read:page:confluence. Re-authorize after scope changes.
  • The Confluence MCP OpenAPI spec does not expose createSpace (experimental); you can still keep write:space:confluence if other space-management tools need it.

For Documentation Management:

read:page:confluence
read:space:confluence
read:attachment:confluence
read:comment:confluence
write:page:confluence
write:attachment:confluence
write:comment:confluence

For Space Administration:

read:page:confluence
read:space:confluence
read:attachment:confluence
read:comment:confluence
write:page:confluence
write:space:confluence
write:attachment:confluence
write:comment:confluence

For Read-Only Access:

read:page:confluence
read:space:confluence
read:attachment:confluence
read:comment:confluence

Step 8: Configure Security​

Set up API protection features:

  1. API Protection: Toggle ON to enable

    • Protects against bot attacks, DDoS, and threats
    • Monitors for suspicious activity
    • Rate limiting and anomaly detection

  2. Protection Features (when enabled):

    • Auto-scaling protection
    • Managed infrastructure
    • Built-in monitoring
    • Zero maintenance required

  3. Click Next to continue

Step 9: Choose Deployment Method​

Select your deployment preference:

  • Fully managed deployment
  • Automatic scaling and monitoring
  • Built-in high availability
  • Features included:
    • Auto-scaling
    • Managed infrastructure
    • Built-in monitoring
    • Zero maintenance

Option B: Deploy with Helm Chart​

  • Self-managed Kubernetes deployment
  • Full control over infrastructure
  • Requires:
    • Kubernetes cluster
    • Helm 3.x installed
    • Container registry access

Click Next after selecting your deployment method.

Step 10: Review and Deploy​

Review your MCP server configuration:

  • MCP Server Name: Your chosen name
  • Base URL: https://api.atlassian.com/ex/confluence/{cloudid}
  • Selected Endpoints: Number of endpoints selected
  • Authentication: OAuth 2.0 (Configured)
  • API Protection: Enabled/Disabled
  • Deployment: Cequence Cloud or Helm

Click Create & Deploy to finalize the setup.

Step 11: Post-Deployment Setup​

After successful deployment:

  1. Note the MCP Server URL provided

  2. Test the OAuth flow:

    • Click "Test Connection"
    • You'll be redirected to Atlassian authorization
    • Select Confluence site to authorize
    • Grant requested permissions
    • Confirm successful connection

  3. Configure AI Agents:

    • The MCP server is now available for AI agent connections
    • Use the provided server URL in your AI agent configuration

Using Your Confluence MCP Server​

Setup Instructions:

Common Use Cases​

Documentation Management​

  • Technical documentation maintenance
  • API reference generation
  • Release notes automation
  • Knowledge base organization

Team Collaboration​

  • Meeting notes management
  • Project documentation
  • Decision logging
  • Team wikis

Process Documentation​

  • Standard operating procedures
  • Onboarding guides
  • Training materials
  • Compliance documentation

Knowledge Sharing​

  • Best practices library
  • Troubleshooting guides
  • FAQ management
  • Lessons learned

Security Best Practices​

  1. OAuth Security:

    • Use minimum required scopes
    • Implement token rotation
    • Store credentials securely
    • Monitor OAuth usage

  2. API Rate Limits:

    • Respect 10 req/sec limit
    • Implement request queuing
    • Use batch operations
    • Cache frequently accessed content

  3. Content Security:

    • Validate content before posting
    • Sanitize HTML input
    • Respect space permissions
    • Audit content changes

  4. Access Control:

    • Use space-level permissions
    • Implement content restrictions
    • Regular permission audits
    • Monitor access patterns

Troubleshooting​

Common Issues​

  1. 401 Unauthorized

    • Verify OAuth token validity
    • Check Confluence site access
    • Ensure correct permissions
    • Re-authenticate if needed

  2. 403 Forbidden

    • Check space permissions
    • Verify page restrictions
    • Ensure app has access
    • Check content permissions

  3. 429 Rate Limited

    • Atlassian limit: 10 req/sec
    • Implement exponential backoff
    • Use expansions to reduce calls
    • Consider caching

  4. 400 Bad Request

    • Validate content format
    • Check required fields
    • Verify CQL syntax
    • Review API documentation

Getting Help​

Use CQL for fine-grained control over search results — for example, type=page AND space=ENG AND text~"api documentation" finds all pages mentioning "api documentation" in the Engineering space.