Getting Started (End Users)

This guide walks you through connecting an MCP-capable AI client (e.g. Claude Desktop) to your Confluence content via the Secure MCP Server for Confluence.

1. Generate a session token

1. In Confluence, open the Connect MCP page (added by this app to your site's global pages).
2. Pick an expiration date. Tokens can last up to 90 days from today.
3. Pick an access level (see below).
4. Click Generate MCP session token.
5. Copy the token shown - it's only displayed once. Treat it like a password: anyone with this token can read any Confluence content you have access to, until it's revoked or expires.

You can only have one active token at a time. Generating a new one automatically revokes the previous one.

Access level

Choose what the token is allowed to do:

• Read-only - search and read pages, spaces, and comments. The page-editing and comment tools are not offered to your AI client at all, and are refused if it tries to call them anyway.
• Read & write - everything in read-only, plus create and edit pages and add comments. Anything written is attributed to you.

Pick read-only unless you actually intend to let the AI write. You can revoke and regenerate at any time to change level.

If your admin has disabled the write tools site-wide, the read & write option is greyed out and the page tells you so. Once a token exists, the Allowed actions panel on the Connect MCP page shows what it can really do - your access level combined with what your admin has enabled.

2. Connect your MCP client

Once the token is generated, the Connect MCP page shows a tab per AI tool - Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and Codex CLI. Each tab gives you:

• where that tool's config file lives (e.g. ~/.cursor/mcp.json for Cursor, ~/.codex/config.toml for Codex CLI),
• a ready-to-paste snippet with your endpoint URL and token already filled in,
• a Copy button.

Claude Code additionally offers a claude mcp add command you can run instead of editing a file. Claude Desktop's snippet connects through the npx mcp-remote bridge rather than a direct HTTP entry, because its connector UI only accepts OAuth.

Paste the snippet into the file shown, then restart the AI tool.

3. Use it

Once connected, ask your AI client things like:

• "Search Confluence for our Q3 roadmap"
• "List the spaces I have access to"
• "Get the comments on page 12345"
• "Show me the content of the 'Onboarding Guide' page"
• "Draft a new page in the DEV space summarizing this conversation"
• "Add a comment to page 12345 with the decision we just made"

The client decides when to call these tools based on your prompt. For the full list of tools and their parameters, see the Tools Reference - note that which tools are available depends on your admin's settings.

Your prompt does the heavy lifting

The quality of what you get back depends almost entirely on how you ask. The AI has no built-in knowledge of your Confluence; it can only find what your words point it to, so a vague request produces vague results. Working through MCP is an iterative loop, not a single command:

• Be specific. Name the space, the page title, the time frame, or the exact keywords you're after. "Find the incident post-mortem from last week in the SRE space" beats "find that doc about the outage".
• If it fails, rephrase. When a search comes back empty or off-target, say the same thing a different way - swap in synonyms, drop jargon, or try the terms an author would actually have written on the page. A missing result usually means a keyword mismatch, not missing content.
• Refine step by step. Start broad to see what exists, then narrow down. Feed what you learned from one answer into your next request, and keep tightening until you land on what you need.

Token lifecycle

• Expiration: up to 90 days; you choose the exact date when generating.
• Renewal: generate a new token at any time - it replaces the old one immediately.
• Revoking: click Revoke access on the Connect MCP page. Do this immediately if a token is exposed (e.g. committed to a repo, pasted somewhere public).
• Expired tokens: the page shows a warning and lets you remove the expired entry; you'll need to generate a new one to keep using the integration.

What the AI can and cannot do

• ✅ Search pages and blog posts, list spaces, read a page's content and comments.
• ✅ Create and update pages, and add comments - always as you, using your own account, and only if you generated a read & write token.
• ✅ See your own account details (name, email, timezone, personal space) so it can act on "my" and read dates like "this week" in your timezone. Your admin can turn this off site-wide.
• ❌ Cannot see or change anything you don't already have permission to in Confluence. The app calls Confluence on your behalf using your own account, so your existing permissions always apply.
• ❌ Cannot delete content - there are no delete tools.
• An admin may have disabled the write tools (Create pages and/or Add comments) or Account info for everyone, or restricted which spaces and content are reachable - see the Admin Guide.
• By default, page and comment content returned to your AI client is scanned for hidden instructions embedded in the content (indirect prompt injection) before it's passed along, and flagged as untrusted data. An admin can turn this off site-wide; see Admin Guide → Content sanitization.
• Every tool call you make is recorded in your admin's audit log, along with the resolved search query for searches - see Admin Guide → Audit log.

Troubleshooting

Symptom	Likely cause	Fix
Client reports an auth/401 error	Token missing, mistyped, expired, or revoked	Regenerate the token on the Connect MCP page and update your client config
"Session token expired on ..."	Token's expiry date has passed	Generate a new token
Search returns nothing for content you know exists	An admin filter may be excluding that space, or the query needs different keywords	Try a simpler query, or ask your admin about the configured filter
"This tool needs a read & write token; your token is read-only"	You generated a read-only token	Revoke it on the Connect MCP page and generate a read & write token
Client doesn't offer a create-page or add-comment tool	Your token is read-only, or your admin has disabled that tool category site-wide	Check the Allowed actions panel on the Connect MCP page: it shows whether the restriction is your token or an admin setting
"Rate limit exceeded" error	Too many requests in a short window (e.g. a runaway or looping client)	Wait a short while and retry; if it persists, check what your client is doing in a loop