Skip to main content

​
Common Issues

  • Ensure you’re using API tokens, not your account password
  • Verify the token hasn’t expired
  • Check that JIRA_USERNAME / CONFLUENCE_USERNAME is your email address
  • Verify your Personal Access Token is valid and not expired
  • For older Confluence servers, try basic auth with CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (where token is your password)
mcp-atlassian uses the OS native trust store by default (via truststore), so certificates signed by enterprise CAs installed in Windows Certificate Store, macOS Keychain, or the Linux system CA bundle are trusted automatically.If you still see SSL errors with self-signed certificates that are not in the OS trust store, disable verification:
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
To disable the OS trust store integration (fall back to the bundled certifi CA bundle):
MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE=false
Ensure your Atlassian account has sufficient permissions to access the spaces/projects you’re targeting.

​
Debugging

​
Enable Verbose Logging

# Standard verbose
MCP_VERBOSE=true

# Debug level (includes request details)
MCP_VERY_VERBOSE=true

# Log to stdout instead of stderr
MCP_LOGGING_STDOUT=true

​
View Logs

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

​
MCP Inspector

Test your configuration interactively: 
# With uvx
npx @modelcontextprotocol/inspector uvx mcp-atlassian

# With local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-atlassian run mcp-atlassian

​
Debugging Custom Headers

​
Verify Headers Are Applied

  1. Enable debug logging: 
    MCP_VERY_VERBOSE=true
MCP_LOGGING_STDOUT=true
  2. Check logs for header confirmation: 
    DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}

​
Correct Header Format

# Correct
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2

# Incorrect (extra quotes)
JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"

# Incorrect (colon instead of equals)
JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2

# Incorrect (spaces around equals)
JIRA_CUSTOM_HEADERS=X-Custom = value1
Header values containing sensitive information are automatically masked in logs.

​
Authentication Errors

Cause: Invalid or expired API token.Fix:
  1. Verify your API token at id.atlassian.com/manage-profile/security/api-tokens
  2. Ensure JIRA_USERNAME matches the email associated with the token
  3. Check that the token hasn’t been revoked
# Test your credentials
curl -u "your.email@example.com:your_api_token" \
  "https://your-instance.atlassian.net/rest/api/2/myself"
Cause: Invalid PAT or PAT doesn’t have required permissions.Fix:
  1. Create a new PAT in your Jira/Confluence profile settings
  2. Ensure the PAT has sufficient permissions for the operations you need
  3. Note: Server/DC limits PAT count (max 10 per user)
# Test PAT authentication
curl -H "Authorization: Bearer your_pat_token" \
  "https://jira.your-company.com/rest/api/2/myself"
Cause: Your account doesn’t have permission for the requested operation.Fix:
  • Verify your Jira/Confluence project permissions
  • For write operations, ensure your account has edit permissions
  • For admin-only fields, you may need project admin access
  • Check if READ_ONLY_MODE=true is blocking write tools
Cause: OAuth access token has expired and refresh failed.Fix:
  1. Re-run the OAuth setup: mcp-atlassian --oauth-setup
  2. Ensure your app has offline_access scope for refresh tokens
  3. Check if the OAuth app is still active in your Atlassian developer console

​
Field and Data Errors

Cause: Custom field ID doesn’t exist or isn’t available on the issue type.Fix:
  1. Use jira_search_fields to find the correct field ID
  2. Check if the field is available on the target issue type’s screen
  3. Custom field IDs differ between Cloud and Server/DC instances
jira_search_fields: {"keyword": "story points"}
Cause: The specified issue type doesn’t exist in the project.Fix:
  • Use jira_get_all_projects to see available issue types per project
  • Issue type names are case-sensitive
  • Some issue types (e.g., “Epic”) may require specific project configurations
Cause: File exceeds the 50MB attachment limit.Fix:
  • MCP Atlassian limits inline attachment downloads to 50MB
  • For larger files, access attachments directly via the Jira/Confluence web UI
  • Consider compressing files before uploading

​
Rate Limiting

Cause: You’ve exceeded the Atlassian API rate limit.Fix:
  • Atlassian Cloud: ~100 requests per minute per user (varies)
  • Server/DC: depends on instance configuration
  • Add delays between bulk operations
  • Use batch tools (jira_batch_create_issues, jira_batch_get_changelogs) instead of individual calls
  • Consider using ENABLED_TOOLS to limit which tools are available

​
Connection Issues

Cause: Server/DC instance uses a self-signed or internal CA certificate.Fix:
# Disable SSL verification (not recommended for production)
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
For mTLS (mutual TLS) authentication:
JIRA_CLIENT_CERT=/path/to/client-cert.pem
JIRA_CLIENT_KEY=/path/to/client-key.pem
Cause: Atlassian instance is unreachable or slow to respond.Fix:
  • Default timeout is 75 seconds
  • Increase timeout for slow instances:
JIRA_TIMEOUT=120
CONFLUENCE_TIMEOUT=120
  • Check if a proxy is required:
HTTPS_PROXY=https://proxy.example.com:8443

​
Getting Help

  • Check GitHub Issues for known problems
  • Review SECURITY.md for security-related concerns
  • Open a new issue with debug logs if the problem persists