---
title: "Troubleshooting"
description: "Common issues and debugging tips for MCP Atlassian"
---
# Troubleshooting
## Common Issues
<AccordionGroup>
<Accordion title="Authentication Failures (Cloud)">
- 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
</Accordion>
<Accordion title="Authentication Failures (Server/Data Center)">
- 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)
</Accordion>
<Accordion title="SSL Certificate Issues">
For Server/Data Center with self-signed certificates:
```bash
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```
</Accordion>
<Accordion title="Permission Errors">
Ensure your Atlassian account has sufficient permissions to access the spaces/projects you're targeting.
</Accordion>
<Accordion title="Python Version Issues">
Python 3.14 is not yet supported due to upstream pydantic-core/PyO3 limitations.
**Workaround with uvx:**
```bash
uvx --python=3.12 mcp-atlassian
```
**In IDE configuration:**
```json
{
"args": ["--python=3.12", "mcp-atlassian"]
}
```
</Accordion>
</AccordionGroup>
## Debugging
### Enable Verbose Logging
```bash
# 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
<Tabs>
<Tab title="macOS">
```bash
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
</Tab>
<Tab title="Windows">
```cmd
type %APPDATA%\Claude\logs\mcp*.log | more
```
</Tab>
</Tabs>
### MCP Inspector
Test your configuration interactively:
```bash
# 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:
```bash
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
```bash
# 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
```
<Note>
Header values containing sensitive information are automatically masked in logs.
</Note>
## Getting Help
- Check [GitHub Issues](https://github.com/sooperset/mcp-atlassian/issues) for known problems
- Review [SECURITY.md](https://github.com/sooperset/mcp-atlassian/blob/main/SECURITY.md) for security-related concerns
- Open a new issue with debug logs if the problem persists
