AI Platform Compatibility

Platform compatibility matrix — Claude Desktop, Cursor, Cline, and Cloud vs Server/DC feature comparison

MCP Atlassian works with any MCP-compatible client. This page documents platform-specific notes and known issues.

Compatibility Matrix

Platform	Status	Transport	Notes
Claude Desktop	Fully supported	stdio	Primary development target
Cursor	Fully supported	stdio
Windsurf	Fully supported	stdio
VS Code (Copilot)	Supported	stdio	See Copilot setup
Vertex AI / Google ADK	Supported	stdio / HTTP	Schema sanitization applied automatically
Amazon Bedrock	Compatible	stdio / HTTP	Not explicitly tested
LiteLLM	Compatible	stdio / HTTP	Passes schemas to underlying provider
OpenAI Gateway	Compatible	stdio / HTTP
ChatGPT	Not tested	HTTP	See ChatGPT notes

MCP stdio readiness probe

Maintainers can exercise the public MCP initialize and tools/list boundary without depending on FastMCP internals:

uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian

The default probe does not invoke any Atlassian tool. It emits machine-readable JSON with the negotiated protocol version, discovered tool names, and installed versions of MCP, MCP types, FastMCP, FastMCP slim, and cryptography. Missing distributions are reported as null, making the output useful for comparing supported SDK and framework environments.

Version-specific test lanes can make protocol negotiation an explicit gate:

uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian \
  --expect-protocol-version=2025-11-25 \
  --expect-tool-absent=jira_create_issue

The expected revision is lane-specific. Do not infer it from the installed MCP SDK major version: an SDK can retain an older protocol revision unless the newer protocol era is explicitly selected. See the MCP 2 / FastMCP 4 findings in issue #1541.

Repeat --expect-tool-present or --expect-tool-absent to make public tool discovery an explicit gate. These checks run immediately after tools/list and before any optional staging reads, so they can diagnose policy visibility without contacting Atlassian. Contradictory expectations fail as a probe configuration error.

An explicit --staging-dc-pat profile can additionally call one fixed Jira DC issue and one fixed Confluence DC page. Configure these variables securely before running it:

Variable	Purpose
MCP_READINESS_JIRA_URL	Jira DC staging URL
MCP_READINESS_JIRA_PAT	Jira DC staging personal access token
MCP_READINESS_JIRA_ISSUE_KEY	Fixed issue approved for a read probe
MCP_READINESS_CONFLUENCE_URL	Confluence DC staging URL
MCP_READINESS_CONFLUENCE_PAT	Confluence DC staging personal access token
MCP_READINESS_CONFLUENCE_PAGE_ID	Fixed page approved for a read probe
MCP_READINESS_MAX_RPM	Optional request rate from 1–30; defaults to 30

Then add the live-profile flag to the preceding command:

uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian \
  --staging-dc-pat

The profile fails closed: it forces read-only mode, exposes only jira_get_issue and confluence_get_page, disables retries, limits concurrency to one, and caps traffic at 30 requests per minute. It stops before a live call if any unexpected tool is exposed. Output records only protocol and result shape—it excludes credentials, URLs, request identifiers, and response bodies.

Direct-call policy regressions, including GHSA-3r68, are tested hermetically with a mocked backend. The live staging profile intentionally does not call a hidden write tool: if policy had regressed, such a canary could perform the write it was intended to detect.

Passing this probe verifies the public MCP behaviors it exercises; it does not by itself establish compatibility with a future FastMCP major version.

Schema Compatibility

MCP Atlassian includes automatic schema sanitization to ensure compatibility with strict AI platforms:

• anyOf flattening: Pydantic v2 generates anyOf patterns for optional parameters (T | None). These are automatically collapsed to simple {"type": T} before schemas are sent to clients, since Vertex AI and Google ADK reject anyOf alongside default or description fields.
• No zero-argument tools: All tools have at least one parameter, which is required by some OpenAI-compatible gateways.
• All properties have explicit type: Required by Vertex AI.
• No $defs / $ref: All schemas are fully inlined.

These constraints are enforced by CI tests across all tools.

Platform-Specific Notes

GitHub Copilot

GitHub Copilot’s coding agent supports MCP servers via stdio transport. Key configuration notes:

1. Use stdio transport

   Copilot’s agent mode uses stdio, not HTTP. Configure as a standard MCP server:

   {
     "mcpServers": {
       "mcp-atlassian": {
         "command": "uvx",
         "args": ["mcp-atlassian"],
         "env": {
           "JIRA_URL": "https://your-instance.atlassian.net",
           "JIRA_USERNAME": "[e-mail]",
           "JIRA_API_TOKEN": "your-api-token"
         }
       }
     }
   }
   
2. Verify tool discovery

   If Copilot reports “Retrieved 0 tools”, ensure you are using mcp-atlassian >= 0.16.0 (which includes FastMCP updates for better protocol compliance). Current releases run on FastMCP v3 (>=3.2.4,<4.0.0) while exposing the standard MCP protocol over stdio and HTTP, so MCP clients do not need FastMCP installed. If an older client still cannot discover tools, update the client to a current MCP-compatible release.

3. Docker alternative

   When using Docker, expose via stdio (not HTTP):

   {
     "mcpServers": {
       "mcp-atlassian": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "JIRA_URL=https://your-instance.atlassian.net",
           "-e", "JIRA_USERNAME=[e-mail]",
           "-e", "JIRA_API_TOKEN=your-api-token",
           "ghcr.io/sooperset/mcp-atlassian:latest"
         ]
       }
     }
   }
   

Vertex AI / Google ADK

Vertex AI enforces strict JSON Schema validation. The automatic anyOf flattening resolves the INVALID_ARGUMENT errors previously reported with Google ADK.

If you encounter schema errors, ensure you are running the latest version:

uvx mcp-atlassian@latest

ChatGPT

ChatGPT’s MCP integration has reported vague “violates guidelines” errors. This may be related to schema validation but no specific diagnostics are available. If you encounter this, please open an issue with the exact error message.

HTTP Transport

For platforms that require HTTP transport (e.g., remote deployments, gateways), see the HTTP Transport guide.

Cloud vs Server/Data Center

MCP Atlassian supports both Atlassian Cloud and Server/Data Center deployments, but some features differ between platforms.

Authentication Methods

Method	Cloud	Server/DC
API Token (username + token)	Yes	Yes (username + password)
Personal Access Token (PAT)	No	Yes
OAuth 2.0	Yes (3LO)	Yes (Application Links)
BYOT (Bring Your Own Token)	Yes	Yes

Tool Availability

Tool	Cloud	Server/DC	Notes
jira_batch_get_changelogs	Yes	No	Cloud-only changelog API
jira_get_issue_proforma_forms	Yes	No	Cloud-only (requires cloud_id for Forms API)
jira_get_service_desk_queues	Yes	Yes	Requires Jira Service Management
confluence_get_page_views	Yes	No	Cloud-only analytics API
confluence_check_content_permissions	Yes	No	Cloud-only content permissions API
confluence_get_space_permissions	Yes	No	Cloud-only space permissions API
confluence_search_user	Yes (CQL)	Yes (group member fallback)	Server/DC uses group member API; specify group_name

Content Format Differences

Feature	Cloud	Server/DC
Issue descriptions	ADF (Atlassian Document Format)	Wiki markup
Confluence pages	Storage format (XHTML)	Storage format (XHTML)
Markdown input	Auto-converted to ADF	Auto-converted to wiki markup
Rich text rendering	ADF JSON	Wiki markup

MCP Atlassian handles format conversion automatically — you always write in Markdown regardless of platform. The tools convert to the appropriate format (ADF for Cloud, wiki markup for Server/DC).

API Differences

Aspect	Cloud	Server/DC
Base URL	*.atlassian.net	Custom domain
API version	REST API v2 + v3	REST API v2
User identifiers	accountId	username or userKey
Rate limiting	Enforced (~100 req/min)	Instance-dependent
Webhooks	Cloud-managed	Self-managed

When switching between Cloud and Server/DC, custom field IDs will be different. Use jira_search_fields to discover the correct field IDs for your instance.