> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-atlassian.soomiles.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#github-copilot)      |
| 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](#chatgpt)             |

## MCP stdio readiness probe

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

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/sooperset/mcp-atlassian/issues/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:

```bash theme={null}
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:

<Steps>
  <Step title="Use stdio transport">
    Copilot's agent mode uses stdio, not HTTP. Configure as a standard MCP server:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Docker alternative">
    When using Docker, expose via stdio (not HTTP):

    ```json theme={null}
    {
      "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"
          ]
        }
      }
    }
    ```
  </Step>
</Steps>

### 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:

```bash theme={null}
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](https://github.com/sooperset/mcp-atlassian/issues) with the exact error message.

## HTTP Transport

For platforms that require HTTP transport (e.g., remote deployments, gateways), see the [HTTP Transport](/docs/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                   |

<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).
</Tip>

### 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.
</Warning>