Skip to main content

Use with AI Agents (Rovo and MCP)

Enhanced Markdown for Confluence ships two ways for AI agents to work on your Markdown content, both driving the same four tools:

  1. The built-in Rovo agent — lives in Confluence chat, picks up the page you are looking at, and needs no setup beyond installing the app.
  2. An MCP server — exposes the same tools to agents you compose in Rovo Studio and to third-party AI clients such as Claude Code and Cursor.

Every call runs with the invoking user's own Confluence permissions — an agent can only read and change what that person could change in the editor.

The Four Tools​

ToolWhat it doesKey inputs
create-markdownAdds a Markdown block to a page/blogpost, or creates a new page/blogpost from itmarkdown; for a new page also pageTitle and spaceKey
get-markdownReads the Markdown source and the page versioncontentId (+ index when the page has several blocks)
update-markdownReplaces a Markdown block with a version-checked writemarkdown, contentId (+ version from the last read)
convert-markdown-blocksTurns markdown code blocks on a page into rendered Enhanced Markdown blocks, in placecontentId

All rendering features work through the tools exactly as in the editor: headings, tables, fenced code with syntax highlighting, KaTeX math ($...$ inline, $$...$$ display), and Mermaid diagrams in ```mermaid fences.

In Confluence Chat (Rovo Agent)​

Open Rovo chat in Confluence and ask. The agent picks up the page you are viewing automatically — "rewrite this page's intro", "add a troubleshooting section to this page", "show me the markdown on this page". Write actions ask for your confirmation before anything changes.

No admin setup is needed: the agent is available the moment the app is installed.

Use with Any AI Client (MCP)​

The app exposes its four tools as an MCP (Model Context Protocol) server, so they work in two more places beyond the built-in agent:

  1. Rovo Studio agents you build yourself — in Rovo Studio, create an agent, choose Add tools → Connected apps, and add the four Enhanced Markdown tools next to tools from any other app.

  2. Third-party MCP clients — Claude Code, Cursor, and anything that speaks MCP can connect directly to the app's endpoint:

    https://mcp.atlassian.com/forge/6c4adb40-91c3-41db-8804-db25b2998069

Admin setup: expose the tools (required for third-party clients)​

External MCP access is disabled by default — until a site or org admin turns it on, clients can authenticate but will not see the tools. One-time per site:

  1. Sign in to admin.atlassian.com as a site or organization admin and open your organization.
  2. Go to Apps → Sites and select your site (e.g. your-site.atlassian.net).
  3. Open Connected apps and select Enhanced Markdown for Confluence.
  4. In the app details, find Tools and switch on the four markdown tools, then save.

Good to know:

  • The toggle is per site — enabling it on one site does not expose the tools on any other site.
  • The built-in Rovo agent does not need this toggle.
  • Each user still approves their own client through OAuth — the admin toggle only makes the tools visible to connect.

Example: connect Claude Code​

Once the admin setup above is done, in a terminal:

# 1. Register the MCP server. --scope user makes it available in every
#    project; without it, Claude Code registers it for the current project only.
claude mcp add --scope user --transport http enhanced-markdown \
  https://mcp.atlassian.com/forge/6c4adb40-91c3-41db-8804-db25b2998069

# 2. Confirm it is registered
claude mcp list
#   enhanced-markdown: https://mcp.atlassian.com/forge/6c4adb40-… - ! Needs authentication
  1. Start claude and run /mcp, select enhanced-markdown, choose Authenticate. A browser opens the Atlassian OAuth 2.1 consent screen — sign in, select your site, and approve.
  2. claude mcp list should now show ✔ Connected. Try real prompts:

Create a page titled "API Style Guide" in our DEV space from this markdown: …

Read the markdown on https://your-site.atlassian.net/wiki/spaces/TEAM/pages/123456789/Architecture and tighten the wording

Update the markdown on page 123456789 — replace the "Draft" warning box with a final release note

Convert the markdown code blocks on https://your-site.atlassian.net/wiki/spaces/TEAM/pages/987654321/Imported-Notes into rendered blocks

Notes learned the hard way:

  • Until the OAuth step is done, the server shows ! Needs authentication and non-interactive Claude runs skip it silently — always check claude mcp list first.
  • There is no open-page context over MCP: point the client at the page URL (or its numeric ID) or a space key in your prompt. The page ID is the number in …/pages/123456789/Title.
  • Cursor and other MCP clients: add the same URL as a remote (HTTP) MCP server; the OAuth flow works the same way.

Multiple Markdown Blocks on One Page​

A page can hold several Enhanced Markdown macros — for example a spec document and an appendix. The tools never guess between them:

  • get-markdown and update-markdown stop and ask which block you mean (numbered 1, 2, 3… from top to bottom) whenever a page has more than one. Pass that number as index.
  • create-markdown in append mode always adds a new block at the end and reports the new total.

If an agent asks "which markdown block do you mean?", answer with the position on the page — "the second one".

How Writes Stay Safe​

  • Version locking — updates carry the version from your last read. If someone edited the page in between, the tool reports the mismatch instead of overwriting their changes; re-read and retry.
  • Open drafts are synced, not clobbered — if the page has an unpublished draft in an open editor, the tool writes into that draft and republishes the same body, so the editor never resurrects stale content. Refresh the editor tab afterwards.
  • No silent targets — if a request could plausibly mean two different pages, the tool refuses and asks rather than picking one. A wrong-page write is the one failure this feature must never have.
  • Your permissions, every call — the server acts as you through Atlassian's own OAuth layer. Nothing is granted to the client that you do not already have.

Troubleshooting​

claude mcp list shows ! Needs authentication forever. Run /mcp inside a claude session and complete the browser consent once. Non-interactive runs (scripts, CI) will not trigger the browser flow.

The server connects but the client sees no tools. The site admin has not flipped the Tools toggle in Atlassian Administration yet — see Admin setup.

A tool says "no Enhanced Markdown macro found". The page has no markdown block yet. Either add one with create-markdown, or convert existing markdown code blocks with convert-markdown-blocks (the code block's language must be set to markdown or md).

You want to import markdown into Confluence. Hand the markdown to your agent together with the target page URL — create-markdown appends it as a rendered block, and convert-markdown-blocks converts markdown code blocks already sitting on a page. Both beat a manual copy-paste: the result is live Confluence content, not pasted text.

A tool asks which block I mean. The page has several markdown macros. Count them from the top of the page and answer with the position — the agent will retry with that index.

Version mismatch on update. Someone changed the page after your last read. Call get-markdown again and retry with the fresh version.

Support​

For issues or feature requests, please visit the app's listing on the Atlassian Marketplace.

Was this helpful?