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

# Authentication

> Configure authentication for MCP Atlassian — API tokens, PATs, mTLS, and OAuth 2.0

MCP Atlassian supports four authentication methods depending on your Atlassian deployment type.

## API Token (Cloud) - Recommended

The simplest method for Atlassian Cloud users.

<Steps>
  <Step title="Create API Token">
    Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
  </Step>

  <Step title="Generate Token">
    Click **Create API token**, give it a name
  </Step>

  <Step title="Copy Token">
    Copy the token immediately - you won't see it again
  </Step>
</Steps>

**Environment variables:**

```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token
```

## Personal Access Token (Server/Data Center)

For Server or Data Center deployments.

<Steps>
  <Step title="Access Profile">
    Go to your profile (avatar) → **Profile** → **Personal Access Tokens**
  </Step>

  <Step title="Create Token">
    Click **Create token**, name it, set expiry
  </Step>

  <Step title="Copy Token">
    Copy the token immediately
  </Step>
</Steps>

**Environment variables:**

```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=your_personal_access_token

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=your_personal_access_token
```

<Note>
  For multi-user HTTP deployments where clients send their own PATs, follow the
  [Server/DC per-request authentication setup](/docs/http-transport#authentication-methods).
  That setup uses non-empty server-side PAT values only to initialize the service
  configuration; each request's `Authorization: Token ...` value replaces them.
</Note>

<Note>
  Enterprise CA certificates in the OS trust store (Windows Certificate Store, macOS Keychain, Linux system CAs) are trusted automatically.
  For self-signed certificates not in the OS trust store, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false`.
</Note>

## Client Certificate (mTLS) (Server/Data Center)

Use mutual TLS when your Jira or Confluence Server/Data Center instance requires a client certificate. This authentication method does not require a username, API token, or personal access token.

Set `*_CLIENT_CERT` to either a combined certificate-and-private-key PEM, or set it with the matching `*_CLIENT_KEY` when the certificate and key are separate files:

```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_CLIENT_CERT=/etc/mcp-atlassian/jira-client-cert.pem
JIRA_CLIENT_KEY=/etc/mcp-atlassian/jira-client-key.pem

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_CLIENT_CERT=/etc/mcp-atlassian/confluence-client-combined.pem
```

In the example, Jira uses separate certificate and key files, while Confluence uses a combined PEM. For a combined PEM, omit `*_CLIENT_KEY`. The matching `JIRA_*` and `CONFLUENCE_*` variables configure each service independently.

<Warning>
  **Encrypted private keys are not supported.** If your key is passphrase-protected, decrypt it first:

  ```bash theme={null}
  openssl rsa -in encrypted.key -out decrypted.key
  ```

  `JIRA_CLIENT_KEY_PASSWORD` and `CONFLUENCE_CLIENT_KEY_PASSWORD` are recognised environment variables but will raise a configuration error at startup if set to a non-empty value.
</Warning>

<Note>
  If your Server/DC instance uses a self-signed or internal CA certificate alongside mTLS, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false` as well.
</Note>

<Note>
  When using mTLS as the sole authentication method, MCP clients that connect without an `Authorization` header (such as a locally running OpenCode instance) will be rejected by default. Set `ALLOW_GLOBAL_CRED_FALLBACK=true` to allow the server to use the configured certificate credentials for requests that carry no per-request auth header:

  ```bash theme={null}
  ALLOW_GLOBAL_CRED_FALLBACK=true
  ```

  Only set this when the server is not exposed to untrusted callers, as it allows any unauthenticated client to transact under the operator's certificate identity.
</Note>

## OAuth 2.0 (Cloud) - Advanced

OAuth 2.0 provides enhanced security features but requires more setup. For most users, API Token authentication is simpler and sufficient.

### Setup Steps

<Steps>
  <Step title="Create OAuth App">
    Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and create an "OAuth 2.0 (3LO) integration" app
  </Step>

  <Step title="Configure Permissions">
    Add scopes for Jira/Confluence as needed
  </Step>

  <Step title="Set Callback URL">
    Set to `http://localhost:8080/callback`
  </Step>

  <Step title="Run Setup Wizard">
    ```bash theme={null}
    # Using uvx
    uvx mcp-atlassian --oauth-setup -v

    # Or using Docker
    docker run --rm -i \
      -p 8080:8080 \
      -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
      ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
    ```
  </Step>

  <Step title="Complete Authorization">
    Follow prompts for Client ID, Secret, URI, and Scope, then complete browser authorization
  </Step>
</Steps>

**Environment variables (after setup):**

```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_wizard
ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_client_id
ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_client_secret
ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
```

<Warning>
  Include `offline_access` in your scope to allow automatic token refresh.
</Warning>

### MCP OAuth Proxy (DCR + Discovery)

Enable this when running a remote MCP endpoint that should onboard MCP clients
through the standard OAuth discovery/DCR flow (`401` challenge, `/.well-known/*`,
`/register`, `/authorize`, `/token`, callback).

```bash theme={null}
ATLASSIAN_OAUTH_PROXY_ENABLE=true
PUBLIC_BASE_URL=https://mcp.example.com/mcp-atlassian
ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,http://127.0.0.1:*,https://chatgpt.com/connector_platform_oauth_redirect
ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES=authorization_code,refresh_token
ATLASSIAN_OAUTH_REQUIRE_CONSENT=true
```

<Note>
  This mode is opt-in. Existing API token, PAT, and header-based OAuth flows continue
  to work without enabling the proxy.
</Note>

<Warning>
  The callback configured in `ATLASSIAN_OAUTH_REDIRECT_URI` is for the upstream
  Atlassian identity provider, not a dynamically registered MCP client. A DCR
  client's `redirect_uri` must be different from this OAuth proxy IdP callback.
  Registration is rejected with `invalid_redirect_uri` if the two callbacks collide,
  preventing a callback loop.
</Warning>

### Bring Your Own Token (BYOT)

If you manage OAuth tokens externally (e.g., through a central identity provider):

```bash theme={null}
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id
ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_access_token
```

<Warning>
  Token refresh is your responsibility - the server does not handle it for BYOT.
</Warning>

### Multi-Cloud OAuth

For multi-tenant applications where users provide their own OAuth tokens:

1. Enable minimal OAuth mode:
   ```bash theme={null}
   # Using uvx
   ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000

   # Or using Docker
   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000
   ```

2. Users provide authentication via HTTP headers:
   * `Authorization: Bearer <user_oauth_token>`
   * `X-Atlassian-Cloud-Id: <user_cloud_id>`

See [HTTP Transport](/docs/http-transport) for more details on multi-user authentication.