---
title: "Connect Confluence to ChatGPT: Manage pages, users, and spaces"
slug: connect-confluence-to-chatgpt-manage-pages-users-and-spaces
date: 2026-06-08
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "Learn how to connect Confluence to ChatGPT using Truto's MCP Server. Overcome Atlassian API quirks, configure secure tool calling, and manage knowledge bases directly from chat."
tldr: "Connect Confluence to ChatGPT using Truto's Model Context Protocol (MCP) servers. Expose pages, spaces, and user management endpoints to LLMs with strict RBAC. This guide covers API quirks, tool configuration, and security settings."
canonical: https://truto.one/blog/connect-confluence-to-chatgpt-manage-pages-users-and-spaces/
---

# 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](https://truto.one/connect-confluence-to-claude-search-and-update-team-documentation/), or for programmatic workflows, see our tutorial on [connecting Confluence to AI Agents](https://truto.one/connect-confluence-to-ai-agents-automate-content-and-permissions/).

By leveraging the [Model Context Protocol (MCP)](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), you can expose Confluence's REST APIs directly to ChatGPT, turning it into an intelligent assistant capable of [searching documentation](https://truto.one/connect-google-to-chatgpt-automate-emails-docs-scheduling/), generating pages, and [managing permissions](https://truto.one/connect-jira-to-chatgpt-automate-issue-tracking-task-updates/) - 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.

```bash
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:

```json
{
  "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:

```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](https://truto.one/integrations/detail/confluence) 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.

> Want to connect your AI agents to Confluence securely? Let's discuss your MCP architecture.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)