Connect Confluence to ChatGPT: Manage pages, users, and spaces

This guide demonstrates how to connect Confluence to ChatGPT using Truto's SuperAI MCP Server. If your team uses Claude, check out our guide on connecting Confluence to Claude, or for programmatic workflows, see our tutorial on connecting Confluence to AI Agents.

By leveraging the Model Context Protocol (MCP), you can expose Confluence's REST APIs directly to ChatGPT, turning it into an intelligent assistant capable of searching documentation, generating pages, and managing permissions - all without writing custom integration code.

The Engineering Reality: Confluence API Quirks

Integrating with the Confluence API is notoriously complex. Before feeding endpoints to an LLM, it is critical to understand the platform-specific behavior that will impact your agent's success:

1. Atlassian Document Format (ADF): Confluence does not natively store pages in simple Markdown or raw HTML. It uses Atlassian Document Format, a highly structured, nested JSON format. Creating or updating a page requires passing the body content in the correct format (e.g., storage format, which is XML-based macros, or ADF). If your LLM attempts to send raw Markdown to the create_a_confluence_page tool, the API will reject it.
2. Versioning Constraints on Updates: You cannot simply PATCH a Confluence page. The update_a_confluence_page_by_id endpoint requires the current version number incremented by exactly 1. Changing a page's status from 'current' to 'draft' effectively deletes an existing draft, and restoring 'trashed' pages requires specific state management. Your agent must fetch the page first, read the current version, and supply version.number + 1 in the update payload.
3. CQL Deprecations and Privacy: Confluence Query Language (CQL) is powerful for searching content and users. However, Atlassian has deprecated user-specific CQL fields (like searching by exact username) in favor of opaque accountId strings due to GDPR and privacy updates. Agents need to handle accountId references directly rather than relying on human-readable names when modifying group memberships or authors.

Step 1: Creating the Confluence MCP Server

Truto automatically generates MCP-compatible JSON-RPC tools based on the integration's OpenAPI specification. You can spin up an MCP server scoped to a specific Confluence workspace either via the Truto UI or programmatically via the API.

Approach A: Via the Truto UI

1. Navigate to your Truto dashboard and locate the connected Confluence integrated account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server (e.g., set allowed methods to read if you only want ChatGPT to search and read pages, or leave blank to allow all CRUD operations).
5. Click Create and copy the generated MCP server URL (https://api.truto.one/mcp/...).

Approach B: Via the API

You can dynamically provision an MCP server for a specific Confluence tenant using the Truto REST API. This generates a secure token stored in a distributed key-value store for high-availability access.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ChatGPT Confluence Access",
    "config": {
      "methods": ["read", "write"]
    }
  }'

The response returns the URL your LLM client will connect to:

{
  "id": "mcp_123456789",
  "name": "ChatGPT Confluence Access",
  "config": {
    "methods": ["read", "write"]
  },
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Step 2: Connecting the MCP Server to ChatGPT

Once you have your Truto MCP URL, you can plug it into ChatGPT to expose the Confluence tools.

Via the ChatGPT UI (Custom Connectors)

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode (required for MCP capabilities).
3. Under MCP servers / Custom connectors, click Add new server.
4. Name: Enter a recognizable name (e.g., "Confluence Workspace").
5. Server URL: Paste the Truto MCP URL obtained in Step 1.
6. Click Save. ChatGPT will immediately ping the endpoint and list the available tools.

Via Manual Configuration

If you are using a localized ChatGPT client wrapper or managing configurations for an enterprise deployment, you can inject the server URL manually into your environment's MCP configuration JSON:

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-remote",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN"
      ]
    }
  }
}

Confluence Tool Inventory

Truto automatically maps the Confluence integration resources into standard MCP tools.

Hero Tools

These are the core tools your agent will use most frequently to interact with Confluence.

list_all_confluence_search

Searches Confluence content using the Confluence Query Language (CQL). It returns an array of matching content including IDs, types, titles, spaces, and excerpts.

• Contextual usage: Use this as the entry point when a user asks "Do we have documentation on X?" Note that user-specific CQL fields are deprecated, so search by text or space key.
• Example Prompt: "Search Confluence for the Q3 marketing roadmap."

get_single_confluence_page_by_id

Retrieves the full content and metadata of a specific page by its ID. Returns body content, labels, properties, and version details.

• Contextual usage: Call this after a search to read the actual documentation. The LLM must request the correct body format (e.g., storage or atlas_doc_format) to parse it effectively.
• Example Prompt: "Read the contents of the page with ID 987654321."

create_a_confluence_page

Creates a new page in a specific Confluence space. Requires the spaceId and title.

• Contextual usage: When drafting new documentation, the LLM will generate the structure and push it here. Ensure the LLM targets the correct spaceId.
• Example Prompt: "Create a new design spec page in the Engineering space titled 'Auth V2 Architecture'."

update_a_confluence_page_by_id

Updates an existing page. Requires id, status, title, body, and version.number.

• Contextual usage: Critical: The LLM must first fetch the page to get the current version number, increment it by 1, and pass it in the payload. Failing to do so results in an API conflict error.
• Example Prompt: "Add a section about rate limits to the API Guidelines page."

list_all_confluence_spaces

Retrieves a paginated list of spaces in the Confluence instance. Can filter by keys, type (global, personal), and status.

• Contextual usage: Use this to map space keys to spaceId values before creating or searching for content.
• Example Prompt: "List all active engineering spaces."

list_all_confluence_users

Searches for users in Confluence using a CQL query. Returns accountId, displayName, and email (depending on privacy settings).

• Contextual usage: Use this to lookup the accountId of a team member before assigning them permissions or attributing authorship.
• Example Prompt: "Find the Atlassian account ID for Jane Doe."

Workflows in Action

Here is how an LLM utilizes these specific tools to execute complex, multi-step actions in Confluence.

Scenario 1: Drafting and Publishing Documentation

"Find the 'Product Ops' space and create a new page titled 'Q4 Launch Plan'. Populate it with a template containing goals, timelines, and risks."

Execution Steps:

1. list_all_confluence_spaces: The agent searches for the space named "Product Ops" to retrieve the required spaceId.
2. create_a_confluence_page: Using the retrieved spaceId, the agent formats the drafted text into a compatible body structure and sends the creation payload.

Result: The LLM returns a success message along with the URL of the newly created page.

Scenario 2: Auditing and Updating Group Permissions

"Check who is in the 'Contractors' group. If John Smith is in it, remove him, as his contract expired."

Execution Steps:

1. list_all_confluence_groups: The agent finds the group ID for "Contractors".
2. list_all_confluence_users: The agent executes a search for "John Smith" to obtain his Atlassian accountId.
3. list_all_confluence_user_groups: The agent checks John Smith's group memberships to confirm he is in the Contractors group.
4. confluence_groups_remove_member: The agent executes the removal using the groupId and accountId.

Result: The agent confirms John Smith has been securely removed from the group, modifying access permissions automatically.

Security and Access Control

Exposing an enterprise knowledge base like Confluence to an AI agent requires strict guardrails. Truto's MCP tokens include several built-in mechanisms to restrict what the LLM can do:

• Method Filtering (config.methods): Restrict the MCP server to specific operation types. For example, setting methods: ["read"] ensures the agent can only execute get and list tools (like searching spaces), blocking create_a_confluence_page entirely.
• Tag Filtering (config.tags): Integration resources are tagged by domain. You can create an MCP token that only exposes ["users", "groups"] tags, allowing IT admin agents to manage personnel without having access to read page content.
• API Token Authentication (require_api_token_auth): By default, possessing the MCP URL is enough to connect. Enabling this flag forces ChatGPT (or the client) to pass a valid Truto API token in the Authorization header, providing a second layer of defense against leaked URLs.
• Automatic Expiration (expires_at): Schedule the MCP token to self-destruct at a specific ISO datetime. This is ideal for granting a temporary chat session access to Confluence, cleaning up the authorization in the background task scheduler automatically.

A Factual Note on Rate Limits

When writing automated workflows against Confluence via ChatGPT, you will likely hit Atlassian's rate limits.

It is important to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the Confluence upstream API returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller (your LLM client).

However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification. Regardless of how Atlassian formats its rate limit headers, you will receive:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

The caller (the agent framework or ChatGPT) is strictly responsible for interpreting these headers, implementing backoff logic, and retrying the request once the ratelimit-reset timestamp has passed.