feat: support Atlassian Cloud scoped (granular) API tokens

[sooperset]

Summary

Atlassian Cloud now offers scoped (granular) API tokens that allow restricting permissions to specific apps and scopes. These tokens are more secure than classic API tokens because they follow the principle of least privilege.

However, scoped API tokens do not work with mcp-atlassian's current Basic Auth configuration.

Root Cause

Scoped API tokens require requests to be routed through the Atlassian API gateway:

• Classic tokens: https://your-site.atlassian.net/rest/api/3/...
• Scoped tokens: https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/...

mcp-atlassian's Basic Auth path uses the site-specific URL from JIRA_URL, so scoped tokens receive 401 Unauthorized.

Verified Test Results

Endpoint	URL	Token	Result
/myself	your-site.atlassian.net	classic	200 OK
/myself	your-site.atlassian.net	scoped	401 Unauthorized
/myself	api.atlassian.com/ex/jira/{cloudId}	scoped	200 OK
get_issue	api.atlassian.com/ex/jira/{cloudId}	scoped	200 OK
search_issues	api.atlassian.com/ex/jira/{cloudId}	scoped	200 OK

Current Workaround

Users can set JIRA_URL to the gateway URL directly:

JIRA_URL=https://api.atlassian.com/ex/jira/{your-cloud-id}
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-scoped-token

This works because is_atlassian_cloud_url() already recognizes api.atlassian.com as a Cloud URL. However, this requires users to know their Cloud ID, which is not intuitive.

Proposed Solution

Add a JIRA_CLOUD_ID (and CONFLUENCE_CLOUD_ID) environment variable. When set alongside a scoped API token, the client would automatically construct the gateway URL:

if self.config.cloud_id and self.config.auth_type == "basic":
    api_url = f"https://api.atlassian.com/ex/jira/{self.config.cloud_id}"
else:
    api_url = self.config.url

Alternatively, auto-detect the Cloud ID from the site URL via GET {site_url}/_edge/tenant_info when a scoped token is detected.

References

• Discussion: Support for API token with scopes #550
• Atlassian docs: Manage API tokens
• Scoped API tokens in Confluence Cloud

[lougovsk]

@sooperset can we enhance the logic please, so that JIRA_URL would still use "your-site.atlassian.net" format and then under the hood get "cloud-id" through "https://your-site.atlassian.net/_edge/tenant_info" call? I guess one would still need a variable to specify that a granular tojen is used.