upload_attachment / upload_attachments always fails on Confluence Data Center

[adrianbastholm]

Bug Description

upload_attachment and upload_attachments tools always fail when uploading files to Confluence Data Center, regardless of file type (PNG, SVG) or file size.

Environment

• MCP server: mcp-atlassian (installed via uvx mcp-atlassian)
• Confluence: Data Center (not Cloud) at a private instance
• uvx version: 0.9.22
• VS Code with Copilot Chat (MCP integration)

Steps to Reproduce

1. Connect to a Confluence Data Center instance using personal token auth
2. Verify page access works (read, update pages all succeed)
3. Try to upload a file:

   upload_attachment(content_id="<valid_page_id>", file_path="/path/to/image.png", comment="test")
   

Expected Behavior

File should be uploaded as an attachment to the specified page.

Actual Behavior

Always returns:

{
  "message": "Attachment uploaded successfully",
  "attachment": {
    "success": false,
    "error": "Failed to upload attachment <filename> to content <page_id>"
  }
}

Note the contradictory response: message says "successfully" but success is false.

What Works

• get_page — works fine
• update_page — works fine (both wiki and markdown formats)
• get_attachments — lists existing attachments fine
• search — works fine
• Manual upload via Confluence UI — works fine (same user, same page)

What Was Tried

• PNG files of various sizes (39KB to 175KB)
• SVG files (4-10KB)
• Single file via upload_attachment
• Multiple files via upload_attachments
• Different page IDs (multiple pages, all editable by the same user)

All fail with the same error. Since all other write operations (update_page) succeed with the same credentials, this appears to be a bug in the attachment upload implementation for Confluence Data Center (as opposed to Cloud).

Workaround

Upload attachments manually via the Confluence UI, then reference them in page content via the MCP update_page tool.

[Troubladore]

Fixed in the community fork via Troubladore/mcp-atlassian#295, integrating #1202.

[koekaverna]

I Have the same problem, put doesn't work for me. POST through API works fine.

[erickalmeidaptc]

Confirming this on a third independent Confluence Data Center environment (confluence.jumia.com, on-prem).

Environment

• mcp-atlassian v0.21.0 installed via uvx mcp-atlassian --env-file .env.mcp
• Confluence Data Center (not Cloud), personal-access-token auth
• Byte-for-byte diff between v0.21.0 and v0.21.1's src/mcp_atlassian/confluence/attachments.py is empty — upgrading to 0.21.1 does NOT fix it, worth calling out since that's the first thing users will try

Symptom — identical to the original report:

{
  "message": "Attachment uploaded successfully",
  "attachment": {
    "success": false,
    "error": "Failed to upload attachment <name> to content <id>"
  }
}

confluence_update_page, confluence_add_label, and every read tool succeed on the same page with the same credentials. Web-UI upload of the same file by the same user to the same page also succeeds. The bug is isolated to confluence_upload_attachment.

Root cause (confirmed by direct code comparison)

_upload_attachment_direct() at src/mcp_atlassian/confluence/attachments.py:490 uses HTTP PUT. The atlassian-python-api library (v4.0.7) — which mcp-atlassian already depends on — implements the equivalent operation with POST and an existing-attachment check in attach_content() (atlassian/confluence/__init__.py:1592). The existing in-tree dependency already has the correct pattern.

Two diagnostic pitfalls I hit that may help others finding this thread:

1. The success/failure response is self-contradictory. Outer envelope says "uploaded successfully", inner payload says success: false. That framing made me initially suspect network flakiness.
2. The real HTTP status code never surfaces to the caller. Lines 504–506:

   except Exception as e:
       logger.error(f"Direct API upload failed: {e}")
       return None

   The response.raise_for_status() on line 493 raises the real error (405/400/403 depending on flavour), it gets logged but swallowed, and the caller (lines 96–103) converts None into the generic "Failed to upload attachment ..." string we all see. Even with log access, you have to know to look there.

Recommended fix (from the perspective of someone just hitting this)

Of the currently open PRs, #1253 (@vu2sar) is the most thorough: it fixes PUT → POST, corrects the X-Atlassian-Token header value ("nocheck" → "no-check"), and — importantly — handles the re-upload case by catching the "same file name" 400 response, looking up the existing attachment id, and POSTing to /child/attachment/{id}/data. Without the re-upload handling, a narrower PR (like #1276 or #1202) would unblock first-time uploads but leave users unable to update attachments — which is the common case for "sync my local file to a Confluence page" workflows (e.g. Claude Code slash-command distribution).

Workaround in the meantime: upload via the web UI. Programmatic label-add on the attachment still works, so any workflow that does upload-then-label can be split — labels persist across attachment versions, so confluence_add_label before or after the manual upload both work.

Happy to test a merged fix against our Data Center instance when it lands.

[SecsAndCyber]

I can reproduce this on Confluence Server/Data Center as well, and the behavior matches this issue very closely.

What I observed

• confluence_upload_attachment fails for valid PNG uploads
• page read operations work
• page update operations work
• listing attachments works
• manual upload through the Confluence web UI works
• the MCP response is contradictory:

{
  "message": "Attachment uploaded successfully",
  "attachment": {
    "success": false,
    "error": "Failed to upload attachment <filename>.png to content <content_id>"
  }
}

Repro shape

1. Connect mcp-atlassian to a Confluence Server/DC instance
2. Use a valid page/content ID
3. Call confluence_upload_attachment with a valid local PNG
4. Observe failure from the tool
5. Upload the same file manually through the Confluence UI
6. Manual upload succeeds

Additional confirmation

In the same environment/session, the following succeeded:

• reading the target page
• updating the target page body
• listing existing attachments on the page

That makes this look attachment-path-specific rather than a general auth or permission problem.

Related issue

This may be related to or explained by #1207, which reports a Server/DC-specific problem with the X-Atlassian-Token header value (nocheck vs no-check).