Skip to main content

​
Troubleshooting

​
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)
For Server/Data Center with self-signed certificates:
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
Ensure your Atlassian account has sufficient permissions to access the spaces/projects you’re targeting.
Python 3.14 is not yet supported due to upstream pydantic-core/PyO3 limitations.Workaround with uvx:
uvx --python=3.12 mcp-atlassian
In IDE configuration:
{
  "args": ["--python=3.12", "mcp-atlassian"]
}

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

​
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