How to Migrate Your Confluence Architecture Docs to Archyl with MCP

Here's a situation I hear about every week. A team adopts Archyl, models their systems in C4, links their ADRs and API contracts — and then someone asks the obvious question: "What about the 200 pages we have in Confluence?"

The first thing to say is the part nobody expects from a vendor: most of those pages should stay in Confluence. Meeting notes, onboarding checklists, the on-call runbook, last quarter's planning doc. Confluence is good at those and Archyl is not trying to take them. What should move is the subset that describes the architecture, and working out which pages those are is most of the job.

The mechanics of the move used to be the hard part. Historically the answer was "wait for an importer" or "copy-paste for an afternoon". Neither is great. But something changed in the last year: both sides of that migration now speak MCP.

Atlassian ships an official remote MCP server that exposes Confluence and Jira to any AI agent, with OAuth and your existing permissions. And Archyl exposes its entire platform — documentation, folders, ADRs, the whole C4 model — through its own MCP server, 181 tools deep.

Put an agent in the middle, and the importer you were waiting for becomes a prompt.

Which pages move, and which stay

Do this before you connect anything. The test I use: would a new engineer need this page to understand how the system works, or to get through their first week? The first belongs next to the model. The second belongs in the wiki.

That sorts a space into four piles.

• Move it as documentation. Pages that describe a system: how the payment service is built, what it talks to, why there's a queue in front of it, what the retry policy is. In Archyl you attach these to the container or system they describe, so they surface with the element instead of three clicks away in a page tree.
• Move it as an ADR. "Why we chose X", RFCs, trade-off write-ups, the post-incident page that ended with a decision. These are decisions, not documentation, and Archyl treats them as a different object with a status and a link to the element they affected.
• Leave it in Confluence. Meeting notes, sprint planning, team handbooks, anything built around a Jira macro that is really a live report. Moving these buys you nothing and costs you the macro.
• Delete it. Every space has pages describing a system that was decommissioned two years ago. A migration is the only time anyone will ever read them again, so it's the only chance you'll get to delete them honestly.

Sorting first is what keeps this from becoming an all-or-nothing migration. You are not emptying Confluence. You are extracting a layer from it.

What you need

• An MCP client. I'll use Claude Code here, but Cursor or any MCP-compatible agent works the same way.
• A Confluence account with read access to the space you want to migrate.
• An Archyl API key — create one in Profile → API Keys with write scope.

Connect both servers

Two commands. First, Atlassian's hosted server (it opens a browser for OAuth the first time you use it):

claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp/authv2

Then Archyl:

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

That's the whole setup. The agent can now read your wiki and write your architecture workspace.

Describe the migration, don't build it

Here's a real prompt, more or less what I used on our own space:

Migrate the "Platform Engineering" Confluence space into my Archyl
project "Aurora Commerce".

1. List the space's page tree and show me the hierarchy first —
   don't import anything yet.
2. Recreate the hierarchy with documentation folders, then import
   each page as markdown. Keep titles, clean up the formatting,
   and rewrite links between imported pages so they point at the
   Archyl versions.
3. Any page that records a decision — "Why we chose X", RFCs,
   trade-off write-ups — should become an ADR instead of a plain
   doc, with an accepted status. Put the original date in the
   first line of the context: "Decided 2024-03-11, migrated from
   Confluence."
4. Give me a summary table of everything you created.

Watch what happens next. The agent calls getConfluenceSpaces and getPagesInConfluenceSpace to map the space, walks the tree with getConfluencePageDescendants, and pulls each page with getConfluencePage. On the Archyl side it mirrors the structure with create_documentation_folder, converts each page to markdown and lands it with create_documentation, then calls move_documentation to file it in the right folder (creating a doc and placing it are two separate tools). And — this is my favorite part — it routes the decision-shaped pages through create_adr instead.

That last step matters more than it looks. Every team's wiki has a layer of fossilized decisions buried under "Documentation". An importer would copy them as-is. An agent reads them, recognizes "Why we moved off RabbitMQ" as an architecture decision, and files it where decisions belong: linked to the element it affected, and queryable next to your C4 model.

The step-zero rule: review before you bulk

Notice that the prompt says "show me the hierarchy first — don't import anything yet". Do that. Every wiki has archive sections, meeting-notes graveyards, and a page called "TEST do not delete" from 2019. Let the agent propose the tree, prune it in one reply ("skip Archive and Meeting Notes"), then let it run.

What 200 pages actually looks like

It is not one prompt and an afternoon. Four things shape how the run actually goes, and knowing them up front is the difference between a clean migration and a half-finished one.

Work section by section, not space by space. The agent keeps context between batches, and a batch you can read the summary of is a batch you can correct. Ten pages, check, next ten.

Atlassian's server throttles, and not at the number you'd expect. An open issue on the official MCP server, filed 29 May 2026 and still without an answer from Atlassian, reports 429s after roughly 20 parallel calls, against a total volume of only 200 to 300 calls over a couple of hours. The reporter's read is that the errors track concurrency spikes rather than sustained load. Whatever the real cap turns out to be, the instruction is the same: tell the agent to work through pages one at a time instead of fanning out.

Re-running a failed batch duplicates it. Archyl doesn't enforce unique documentation slugs, so if a batch dies at page seven of ten and you say "try again", you get two copies of the first six. Ask the agent to call list_documentation and skip what already exists before it retries.

Deep trees get flattened. Archyl caps documentation folders at three levels. A Confluence tree nested deeper comes back with Maximum folder nesting depth (3 levels) reached, so decide which levels collapse before you start rather than discovering it at page 40.

Honest limitations

• Attachments still don't travel by themselves, and the reason has moved. When this post first ran, Archyl had nowhere to put them. It does now: documentation attachments ship, backed by S3-compatible object storage, and an agent holding your API key can post a file straight at a doc. The gap is on the Confluence side. Atlassian's remote MCP server has no attachment tool at all — as of August 2026 the supported tools list twelve Confluence operations and none of them touch files, and the feature request has been open since March 2026. So the agent can't fetch the bytes over MCP. It can fetch them over the Confluence REST API (GET /wiki/api/v2/pages/{id}/attachments returns a downloadLink per file) and then push each one across:

  curl -X POST https://api.archyl.com/api/v1/docs/$DOC_ID/attachments \
    -H "X-API-Key: $ARCHYL_API_KEY" \
    -F "file=@architecture-overview.png"
  

  The response comes back with a ready-made markdown snippet to drop into the page. Any file type, 10 MB each by default. But be clear about what that is: a script, with a second credential (an Atlassian API token, since the OAuth session the MCP server holds isn't yours to borrow). For most spaces, re-uploading the handful of diagrams that actually matter through Archyl's editor is still the faster answer.

• ADRs are dated the day you create them. No API accepts a decision date, MCP or REST, so a decision made in 2023 lands stamped with today. That's why the prompt above writes the original date into the context. Worth knowing before you migrate a decade of decisions in one go.

• Documentation doesn't link itself to your model. The agent can attach an ADR to a system or container in one call (link_adr_to_element). There's no equivalent MCP tool for documentation yet, so imported docs arrive unlinked. Link them in the UI, or have the agent POST to /api/v1/docs/{id}/links with the same API key. Don't skip it: a doc sitting next to the container it describes is the entire reason it left the wiki.

• Complex macros degrade. Confluence's fancier macros — Jira issue tables, dynamic reports — become plain text or links. Code blocks, tables, info panels convert cleanly.

• Permissions are your permissions. The Atlassian MCP server only exposes what your OAuth user can read. That's a feature.

Why this beats a classic importer

A one-shot importer moves bytes. An agent moves meaning: it restructures while it migrates, turns decisions into ADRs, fixes dead formatting, and answers "what did you skip and why" when it's done.

It also makes the sorting possible. No importer will ever look at a page and decide it belongs in the pile you're leaving behind. An agent will, if you tell it the rule.

What it looks like when both are running

The end state isn't one tool. It's a boundary that holds:

• Confluence keeps the wiki job. Notes, plans, handbooks, anything tied to Jira. Nobody has to be told to stop using it, which is why the boundary survives contact with the team.
• Archyl holds the architecture layer. The C4 model, plus the documentation, ADRs and API contracts that describe it, each attached to the element it belongs to. When someone opens the payments container, the doc explaining it and the ADR behind it are right there.
• Both stay reachable to your agents. Your MCP client has both servers connected. It can query the architecture from Archyl and still search the wiki for the planning page, in the same conversation.

There's one rule that keeps this from drifting back, and it's worth saying out loud once: when a page describes a system, it goes in Archyl. The day someone writes a new architecture page in Confluence, you've started the 200-page problem over.

Set up your key, point your agent at both servers, and give it one section to chew on. The full tool list is in the MCP server docs.

And once the docs are across, the same trick works on the architecture itself: Structurizr files, Terraform modules, Mermaid diagrams and the codebase, into a C4 model.