> ## 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, and OAuth 2.0

MCP Atlassian supports three 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>
  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>

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

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