·

Confluence MCP With Claude Code CLI and VS Code

Set up Confluence MCP in Claude Code CLI and VS Code so your AI agent can read and write pages and documentation right from your editor.

Claude Code has the most mature MCP tool-calling loop of the four agents in this course — it plans multi-step Confluence operations (search, then read, then create) without needing hand-holding, and it's honest when a confluence_update_page call fails on a version conflict instead of silently retrying into a mess. This topic wires up mcp-atlassian in both the Claude Code CLI and the VS Code extension, then runs real documentation-generation prompts against a live space.

Installing and Connecting Confluence MCP to Claude Code

Claude Code reads MCP server definitions from .mcp.json (project-scoped, committed to the repo) or from user-scoped config via claude mcp add. For a Confluence server you'll share across a team, .mcp.json in the repo root is the right call — but never commit the token itself; use env var interpolation.

Add the server with the CLI directly:

claude mcp add confluence \
  --scope project \
  -- docker run -i --rm \
    -e CONFLUENCE_URL \
    -e CONFLUENCE_USERNAME \
    -e CONFLUENCE_API_TOKEN \
    -e CONFLUENCE_SPACES_FILTER \
    ghcr.io/sooperset/mcp-atlassian:latest

This writes to .mcp.json:

{
  "mcpServers": {
    "confluence": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "CONFLUENCE_SPACES_FILTER",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Since the args reference bare env var names (no =value), Docker pulls them from the shell environment at launch time — set them in .env (gitignored) and source it before starting Claude Code:

export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_USERNAME="dat.hoang@yourcompany.com"
export CONFLUENCE_API_TOKEN="ATATT3xFfGF0...redacted"
export CONFLUENCE_SPACES_FILTER="ENG,DOCS"

source .env && claude

Verify the connection inside a Claude Code session:

/mcp

This lists connected servers and their tool counts. A healthy confluence entry shows something like 9 tools — if it shows 0 tools or an error status, the Docker container likely failed to start; check with docker logs on the container ID from docker ps -a.

If you'd rather run without Docker, mcp-atlassian also installs via uvx:

claude mcp add confluence --scope project \
  -- uvx mcp-atlassian \
    --confluence-url "$CONFLUENCE_URL" \
    --confluence-username "$CONFLUENCE_USERNAME" \
    --confluence-token "$CONFLUENCE_API_TOKEN"

The uvx path starts faster (no image pull) and is easier to debug locally since stack traces print directly to your terminal instead of being wrapped inside a container.

Tips
- Use --scope project for anything a team shares, --scope user for a personal-only connection you don't want committed to .mcp.json.
- Run /mcp after every config change — Claude Code caches the server list per session and won't pick up edits until you restart or explicitly reconnect.
- If Docker Desktop isn't running, the docker run command hangs silently for ~30 seconds before failing — the uvx install path avoids this dependency entirely.

Reading and Creating Confluence Pages from the Claude Code Terminal

With the server connected, Claude Code's planning model decides which Confluence tools to call and in what order — you don't need to name tools explicitly in most prompts.

Find the page about our rate-limiting design in the ENG space and summarize
the current approach in 5 bullet points.

Claude Code will call confluence_search with a CQL query it constructs itself, then confluence_get_page on the top match, then synthesize the summary. Watch the tool-call transcript (visible inline in the CLI) — it's genuinely useful for catching a wrong-space search before it wastes a round trip.

Creating a page requires more explicit direction, since "creating" is a higher-stakes operation than "reading":

Create a new Confluence page titled "Rate Limiting — Redis Token Bucket
Design" in the ENG space, as a child of the "Architecture Decisions" page.
Content: explain we're moving from a fixed-window counter to a token
bucket algorithm backed by Redis, include the Lua script from
`internal/ratelimit/bucket.lua`, and note the migration is planned for
Q3 2026.

Claude Code reads the referenced file first (a normal file read, not an MCP call), then calls confluence_create_page with a body it converts to Confluence storage format. In practice, the generated page's code block renders correctly, headings map to h2/h3, but nested bullet lists with inline code sometimes flatten one level — worth a manual glance before sharing the link with your team.

Updating an existing page needs the current version number, which confluence_update_page on mcp-atlassian fetches automatically before applying the edit (optimistic locking under the hood) — but if two people edit the same page in the same few seconds, you'll get a version-conflict error back from the API. Claude Code surfaces this plainly rather than silently overwriting:

Error calling tool 'confluence_update_page': Version conflict —
page has been modified since last read. Current version: 14, expected: 13.

The fix is just re-running the update; the agent re-fetches the latest version and retries. It doesn't do this automatically by default — you have to prompt it to retry, which is the right default for anything editing shared documentation.

Tips
- For "read and summarize" prompts, no extra guardrails needed — read-only MCP calls are low risk.
- For "create" or "update" prompts, always specify the exact space key and parent page — an unscoped prompt lets the agent guess the parent, and it sometimes picks the space's root page.
- On a version conflict, don't blindly retry with --force-style prompting ("just overwrite it") — read what changed first, or you'll clobber a teammate's edit.

Confluence MCP in the Claude Code VS Code Extension

The Claude Code VS Code extension shares the same .mcp.json config as the CLI — no separate setup needed if you've already configured the project-scoped server. Open the Claude panel in VS Code, and the Confluence tools appear automatically in the tool-approval list the first time the agent tries to call one.

The meaningful difference from the terminal is context: inside VS Code, the agent already has your currently open files and editor selection as ambient context, so documentation prompts can be scoped tighter without re-typing file paths.

Selection: the `PaymentProcessor` class in payment_processor.py

Prompt: Generate a Confluence page documenting this class's public
interface and error-handling contract. Put it in the ENG space under
"API Reference".

VS Code's inline diff view is where this integration earns its keep for confluence_update_page calls — you see the proposed storage-format change (rendered as a readable diff, not raw XML) before approving it, the same review UX you already use for file edits. That's a meaningfully better review experience than the CLI, where you're reading the tool-call JSON directly.

Tool approval settings matter here: by default, VS Code prompts for approval on every Confluence write call. For a personal sandbox space, you can pre-approve confluence_create_page and confluence_update_page in the extension's settings to skip the prompt — do this only for spaces where a bad write is cheap to revert.

// .vscode/settings.json
{
  "claude-code.mcp.autoApprove": {
    "confluence": ["confluence_search", "confluence_get_page"]
  }
}

Deliberately leave confluence_create_page and confluence_update_page off the auto-approve list for any space that isn't your personal sandbox.

Tips
- Use the VS Code extension's diff view specifically for reviewing confluence_update_page calls — it's the fastest way to catch storage-format regressions before they hit a live page.
- Auto-approve read-only tools (confluence_search, confluence_get_page) freely; keep write tools on manual approval outside sandbox spaces.
- The extension and CLI can run concurrently against the same .mcp.json — useful for having the CLI do a bulk doc-generation pass while you review individual pages in VS Code.

Prompts for Generating Technical Documentation from Source Code

The prompts that consistently produce usable Confluence pages share a pattern: name the exact source, name the exact destination, and constrain the structure. Here are four field-tested templates.

API reference from route definitions:

Read all route handlers in `api/routes/`. For each, extract the HTTP
method, path, request/response schema, and auth requirement. Generate
a single Confluence page "API Reference — v2" in the DOCS space,
organized as one h2 section per resource (Users, Orders, Payments),
with a table of endpoints under each.

Architecture decision record from a PR:

Read the diff in the current branch against main. Draft an ADR for
Confluence: context (what problem this solves), decision (what we
implemented), and consequences (trade-offs, what we gave up). Create
it in ENG under "Architecture Decisions" with today's date in the title.

Runbook from an incident-response script:

Read `scripts/failover.sh` and `scripts/healthcheck.sh`. Generate a
Confluence runbook titled "Database Failover Procedure" for the ENG
space: prerequisites, step-by-step procedure (numbered), rollback steps,
and a "who to page" section referencing the on-call rotation doc
(search for it, link it, don't paraphrase it).

Changelog page synced from git tags:

List commits between tag v2.3.0 and v2.4.0 (git log). Categorize into
Features, Fixes, and Breaking Changes. Update the "Release Notes"
Confluence page in DOCS by appending a new v2.4.0 section at the top,
preserving all existing sections below it.

That last one is the trickiest in practice — "append without touching the rest" requires the agent to fetch the current page body, splice in new content, and push the full updated body back (Confluence's API replaces the whole body, there's no partial-append endpoint). Claude Code handles this reliably as long as you're explicit about preserving existing content; without that instruction, some runs have overwritten the whole page with just the new section.

Tips
- Always state explicitly whether the agent should preserve existing page content or replace it — Confluence's API has no partial update, so the agent must fetch-modify-push the whole body itself.
- For anything referencing another Confluence page (like the on-call rotation link above), instruct the agent to search and link rather than paraphrase — paraphrased content drifts out of sync with the source.
- Review the first AI-generated page of each new "type" (API reference, ADR, runbook) carefully — once the structure is right, subsequent pages of the same type need much lighter review.

Tips

Tips
- Prefer --scope project with a .env-sourced token over hardcoding credentials in .mcp.json — it's the difference between a config file you can safely commit and one you can't.
- The VS Code extension's diff view is the best review surface in this entire course for Confluence writes — use it even if your primary workflow is the CLI, just for spot-checking risky updates.
- Next up: the same server wired into OpenCode, where tool-calling reliability for CQL generation is noticeably rougher — expect to write more explicit prompts there.

Next Confluence MCP With OpenCode