---
name: iblai-connect-confluence
description: "Read and write Confluence data through the Confluence Cloud REST API v2 (plus v1 CQL search) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Confluence data, or to set up a Confluence MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Confluence connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/confluence — not part of the iblai/vibe repository. Checked against Atlassian's documentation on October 20, 2026; test it against your own Confluence setup before you rely on it.

Confluence Cloud holds spaces, pages and blog posts, comments, attachments, labels, whiteboards and the permissions on them, typically used for internal documentation and knowledge bases.

## Auth & conventions

- **API:** Confluence Cloud REST API v2 (plus v1 CQL search) (REST). v2 covers pages, blog posts, comments, attachments, spaces, labels, users and whiteboards with cursor paging. CQL search runs on the v1 endpoint /wiki/rest/api/content/search?cql=.
- **Base URL:** https://{your-domain}.atlassian.net/wiki/api/v2/
- **Access:** Public, self-serve. Direct calls use basic auth with an Atlassian account API token; apps use OAuth 2.0 or JWT. Results are limited to what the authenticated user can see.
- **Auth:** Basic auth with email and API token; OAuth 2.0 authorization code (3LO). Direct REST calls use basic auth and the user's own permissions. Apps use OAuth 2.0 scopes, such as read:page:confluence for reading pages, or user impersonation.
- **Limits:** Points-based: 1 point per core object, 2 per user or group, writes 1 point. Default global pool 65,000 points/hour; enforced from March 2, 2026 for Forge, Connect and OAuth apps. 429 with Retry-After and RateLimit-Reason.
- Keep Confluence credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Pages** — GET /wiki/api/v2/pages and /pages/{id}; scope read:page:confluence. Cursor paging via the Link header.
- **Pages in a space** — GET /wiki/api/v2/spaces/{id}/pages.
- **CQL search** — GET /wiki/rest/api/content/search?cql=... (v1) for text, label, space and date queries.
- **Spaces, comments, attachments** — v2 resources for spaces, comments, attachments and labels.

## Writes

- **Create page** — POST /wiki/api/v2/pages in a space.
- **Update page** — PUT /wiki/api/v2/pages/{id}; PUT /pages/{id}/title renames a page.
- **Delete page** — DELETE /wiki/api/v2/pages/{id}; needs delete permission in the space. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Atlassian publishes an official MCP server, Atlassian Rovo MCP Server (https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Confluence supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Find our current incident response runbook and summarize the escalation steps"
- "Create a meeting notes page in the PRODUCT space under the Q4 Planning page"
- "Which pages in the HR space were updated in the last 30 days?"
- "Update the onboarding checklist page to add the new VPN step"

## Guardrails

- Pages hold internal documentation, policies and project records; spaces may contain personal data or confidential customer information depending on the organization.
- Request the narrowest Confluence scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Confluence REST API v2: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/
- Advanced searching using CQL: https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/
- Confluence rate limiting: https://developer.atlassian.com/cloud/confluence/rate-limiting/
- Atlassian Rovo MCP Server: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
- This connector on ibl.ai: https://ibl.ai/developer/connectors/confluence
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections