Compatibility

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

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:

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

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-instance.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

If Copilot reports "Retrieved 0 tools", ensure you are using mcp-atlassian >= 0.16.0 (which includes FastMCP updates for better protocol compliance).

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

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JIRA_URL=https://your-instance.atlassian.net",
        "-e", "JIRA_USERNAME=your-email@example.com",
        "-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_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

Tip

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

Warning

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.