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.

1. Create API Token

   Go to https://id.atlassian.com/manage-profile/security/api-tokens

2. Generate Token

   Click Create API token, give it a name

3. Copy Token

   Copy the token immediately - you won’t see it again

Environment variables:

JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=[e-mail]
JIRA_API_TOKEN=your_api_token

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=[e-mail]
CONFLUENCE_API_TOKEN=your_api_token

Personal Access Token (Server/Data Center)

For Server or Data Center deployments.

1. Access Profile

   Go to your profile (avatar) → Profile → Personal Access Tokens

2. Create Token

   Click Create token, name it, set expiry

3. Copy Token

   Copy the token immediately

Environment variables:

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

For multi-user HTTP deployments where clients send their own PATs, follow the Server/DC per-request authentication setup. That setup uses non-empty server-side PAT values only to initialize the service configuration; each request’s Authorization: Token ... value replaces them.

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.

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:

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.

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

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.

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.

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:

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.

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

1. Create OAuth App

   Go to Atlassian Developer Console and create an “OAuth 2.0 (3LO) integration” app

2. Configure Permissions

   Add scopes for Jira/Confluence as needed

3. Set Callback URL

   Set to http://localhost:8080/callback

4. Run Setup Wizard

   # 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
   
5. Complete Authorization

   Follow prompts for Client ID, Secret, URI, and Scope, then complete browser authorization

Environment variables (after setup):

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

Include offline_access in your scope to allow automatic token refresh.

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

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

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

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.

Bring Your Own Token (BYOT)

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

ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id
ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_access_token

Token refresh is your responsibility - the server does not handle it for BYOT.

Multi-Cloud OAuth

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

1. Enable minimal OAuth mode:

   # 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 for more details on multi-user authentication.