> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-atlassian.soomiles.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure MCP Atlassian for Claude Desktop, Cursor, Windsurf, and VS Code with environment variables

This guide covers IDE integration, environment variables, and advanced configuration options.

## IDE Integration

### Configuration File Locations

| IDE                      | Location                                                          |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Linux)   | `~/.config/Claude/claude_desktop_config.json`                     |
| Cursor                   | Settings → MCP → + Add new global MCP server                      |

### Basic Configuration (uvx)

```json theme={null}
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

### Docker with Environment File

```json theme={null}
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}
```

### Server/Data Center Configuration

```json theme={null}
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_pat",
        "JIRA_SSL_VERIFY": "false",
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_pat",
        "CONFLUENCE_SSL_VERIFY": "false"
      }
    }
  }
}
```

For mTLS, replace the personal token variables with client certificate variables. Use a combined certificate-and-private-key PEM in `*_CLIENT_CERT`, or use `*_CLIENT_CERT` and the matching `*_CLIENT_KEY` for separate files:

```json theme={null}
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "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/wiki",
        "CONFLUENCE_CLIENT_CERT": "/etc/mcp-atlassian/confluence-client-combined.pem"
      }
    }
  }
}
```

`JIRA_CLIENT_CERT` and `CONFLUENCE_CLIENT_CERT` can point to combined PEM files. If the private key is separate, set `JIRA_CLIENT_KEY` or `CONFLUENCE_CLIENT_KEY` as appropriate. Encrypted private keys aren't supported by the requests library, so decrypt them before starting MCP Atlassian instead of setting `JIRA_CLIENT_KEY_PASSWORD` or `CONFLUENCE_CLIENT_KEY_PASSWORD`.

### Single Service Configuration

<Tabs>
  <Tab title="Confluence Only">
    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian": {
          "command": "uvx",
          "args": ["mcp-atlassian"],
          "env": {
            "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
            "CONFLUENCE_USERNAME": "your.email@company.com",
            "CONFLUENCE_API_TOKEN": "your_api_token"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Jira Only">
    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian": {
          "command": "uvx",
          "args": ["mcp-atlassian"],
          "env": {
            "JIRA_URL": "https://your-company.atlassian.net",
            "JIRA_USERNAME": "your.email@company.com",
            "JIRA_API_TOKEN": "your_api_token"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Environment Variables

### Connection Settings

| Variable                                 | Description                                                                               |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| `JIRA_URL`                               | Jira instance URL                                                                         |
| `JIRA_USERNAME`                          | Jira username (email for Cloud)                                                           |
| `JIRA_API_TOKEN`                         | Jira API token (Cloud)                                                                    |
| `JIRA_PERSONAL_TOKEN`                    | Jira Personal Access Token (Server/DC)                                                    |
| `JIRA_CLIENT_CERT`                       | Jira mTLS client certificate PEM path (Server/DC), combined or certificate-only           |
| `JIRA_CLIENT_KEY`                        | Jira mTLS private key PEM path when the certificate is separate (Server/DC)               |
| `JIRA_CLIENT_KEY_PASSWORD`               | Not supported for encrypted private keys; decrypt the key before use                      |
| `JIRA_SSL_VERIFY`                        | SSL verification (`true`/`false`)                                                         |
| `CONFLUENCE_URL`                         | Confluence instance URL                                                                   |
| `CONFLUENCE_USERNAME`                    | Confluence username (email for Cloud)                                                     |
| `CONFLUENCE_API_TOKEN`                   | Confluence API token (Cloud)                                                              |
| `CONFLUENCE_PERSONAL_TOKEN`              | Confluence Personal Access Token (Server/DC)                                              |
| `CONFLUENCE_CLIENT_CERT`                 | Confluence mTLS client certificate PEM path (Server/DC), combined or certificate-only     |
| `CONFLUENCE_CLIENT_KEY`                  | Confluence mTLS private key PEM path when the certificate is separate (Server/DC)         |
| `CONFLUENCE_CLIENT_KEY_PASSWORD`         | Not supported for encrypted private keys; decrypt the key before use                      |
| `CONFLUENCE_SSL_VERIFY`                  | SSL verification (`true`/`false`)                                                         |
| `MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE`    | Use OS native trust store (`true`/`false`, default: `true`)                               |
| `MCP_ATLASSIAN_VALIDATION_CACHE_TTL`     | Multi-user credential validation cache lifetime in seconds (`0` disables, default: `300`) |
| `MCP_ATLASSIAN_VALIDATION_CACHE_MAXSIZE` | Maximum cached multi-user credential validations (default: `100`)                         |

<Warning>
  Encrypted private keys are not supported. Setting `JIRA_CLIENT_KEY_PASSWORD` or
  `CONFLUENCE_CLIENT_KEY_PASSWORD` to a non-empty value will raise a configuration error
  at startup. Decrypt the key first:

  ```bash theme={null}
  openssl rsa -in encrypted.key -out decrypted.key
  ```
</Warning>

### Filtering Options

| Variable                   | Description                                                      | Example                                          |
| -------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| `JIRA_PROJECTS_FILTER`     | Limit to specific Jira projects                                  | `PROJ,DEV,SUPPORT`                               |
| `CONFLUENCE_SPACES_FILTER` | Limit to specific Confluence spaces                              | `DEV,TEAM,DOC`                                   |
| `ENABLED_TOOLS`            | Enable only specific tools                                       | `confluence_search,jira_get_issue`               |
| `TOOLSETS`                 | Enable tool groups (see [Toolset Filtering](#toolset-filtering)) | `default`, `legacy`, `all`, `default,jira_agile` |

### Jira Key Validation

Jira tools validate their `issue_key` / `project_key` arguments before calling the
API. The defaults match the Cloud key format, which cannot be changed. On Server/Data
Center the format is an instance setting (`jira.projectkey.pattern`), so widen these
patterns if your instance allows keys the defaults reject — a leading digit, a single
character, or lowercase. An invalid regex is ignored (a warning is logged) and the
default is kept. Both are read once at startup.

| Variable                   | Description                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `JIRA_ISSUE_KEY_PATTERN`   | Regex accepted for `issue_key` arguments (default: `^[A-Z][A-Z0-9_]+-\d+(?:-\d+)*$`) |
| `JIRA_PROJECT_KEY_PATTERN` | Regex accepted for `project_key` arguments (default: `^[A-Z][A-Z0-9_]+$`)            |

```bash theme={null}
# Data Center instance whose project keys may start with a digit (e.g. 4ME-123)
JIRA_ISSUE_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*-\d+(?:-\d+)*$
JIRA_PROJECT_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*$
```

### Server Options

| Variable                                       | Description                                                                                                                                                                                    |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSPORT`                                    | Transport type (`stdio`, `sse`, `streamable-http`)                                                                                                                                             |
| `STATELESS`                                    | Enable stateless mode for streamable-http (`true`/`false`)                                                                                                                                     |
| `PORT`                                         | Port for HTTP transports (default: `8000`)                                                                                                                                                     |
| `HOST`                                         | Host for HTTP transports (default: `0.0.0.0`)                                                                                                                                                  |
| `READ_ONLY_MODE`                               | Disable write operations (`true`/`false`)                                                                                                                                                      |
| `MCP_VERBOSE`                                  | Enable verbose logging (`true`/`false`)                                                                                                                                                        |
| `MCP_VERY_VERBOSE`                             | Enable debug logging (`true`/`false`)                                                                                                                                                          |
| `MCP_LOGGING_STDOUT`                           | Log to stdout instead of stderr (`true`/`false`)                                                                                                                                               |
| `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1`        | Download Confluence attachments via the v1 REST endpoint instead of the legacy `/download/` link (removed on Cloud). Unset = auto (v1 on Cloud, legacy on Server/DC); `true`/`false` to force. |
| `ATLASSIAN_OAUTH_PROXY_ENABLE`                 | Enable OAuth proxy + DCR + `/.well-known/*` routes (`true`/`false`)                                                                                                                            |
| `PUBLIC_BASE_URL`                              | Public base URL for OAuth discovery metadata                                                                                                                                                   |
| `ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS` | Comma-separated allowed redirect URI patterns for DCR clients                                                                                                                                  |
| `ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES`          | Comma-separated grant types allowed during DCR                                                                                                                                                 |
| `ATLASSIAN_OAUTH_REQUIRE_CONSENT`              | Require local consent page before upstream redirect (`true`/`false`)                                                                                                                           |
| `IGNORE_HEADER_AUTH`                           | Bypass proxy-injected auth headers. For GCP Cloud Run, AWS ALB deployments where load balancers inject Authorization headers (`true`/`false`)                                                  |

See [.env.example](https://github.com/sooperset/mcp-atlassian/blob/main/.env.example) for all available options.

### HTTP Hardening

These optional safeguards are useful for protecting self-hosted Server/Data Center
instances from runaway request loops. They are disabled by default.

| Variable                              | Description                                                                                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ATLASSIAN_RETRY_TOTAL`               | Enable retries for transient `429/502/503/504` responses and connection errors. `0` or unset disables retries.                                          |
| `ATLASSIAN_RETRY_BACKOFF`             | Retry exponential backoff factor in seconds (default: `1.0` when retries are enabled).                                                                  |
| `ATLASSIAN_RETRY_INCLUDE_WRITES`      | Also retry write methods (`POST`/`PUT`/`PATCH`/`DELETE`). Use only when writes are known to be idempotent.                                              |
| `ATLASSIAN_RETRY_IGNORE_RETRY_AFTER`  | Ignore the server's `Retry-After` header and use exponential backoff instead. Enable this for gateways that emit bogus values such as `Retry-After: 0`. |
| `ATLASSIAN_MAX_CONCURRENT_REQUESTS`   | Process-wide cap for concurrent Jira and Confluence requests. `0` or unset disables the cap.                                                            |
| `ATLASSIAN_REQUESTS_PER_SECOND`       | Process-wide outbound request rate limit. `0` or unset disables the limit.                                                                              |
| `ATLASSIAN_MAX_PAGINATION_LIMIT`      | Clamp user-supplied page sizes for high-fanout list/search calls. `0` or unset disables clamping.                                                       |
| `ATLASSIAN_CIRCUIT_BREAKER_THRESHOLD` | Open a process-wide circuit breaker after this many consecutive `429/503` responses. `0` or unset disables it.                                          |
| `ATLASSIAN_CIRCUIT_BREAKER_COOLDOWN`  | Circuit breaker cooldown in seconds before allowing a probe request (default: `30.0`).                                                                  |

## Proxy Configuration

MCP Atlassian supports routing API requests through HTTP/HTTPS/SOCKS proxies,
with optional PAC/WPAD auto-configuration.

| Variable                                                                                           | Description                                                      |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `HTTP_PROXY`                                                                                       | Global HTTP proxy URL                                            |
| `HTTPS_PROXY`                                                                                      | Global HTTPS proxy URL                                           |
| `SOCKS_PROXY`                                                                                      | Global SOCKS proxy URL                                           |
| `NO_PROXY`                                                                                         | Global hosts to bypass proxy                                     |
| `ATLASSIAN_PROXY_WPAD_ENABLE`                                                                      | Enable global PAC/WPAD evaluation (`true`/`false`)               |
| `ATLASSIAN_PROXY_WPAD_URL`                                                                         | Global PAC URL (defaults to `http://wpad/wpad.dat` when enabled) |
| `JIRA_HTTP_PROXY`, `JIRA_HTTPS_PROXY`, `JIRA_SOCKS_PROXY`, `JIRA_NO_PROXY`                         | Jira-specific explicit proxy overrides                           |
| `JIRA_PROXY_WPAD_ENABLE`, `JIRA_PROXY_WPAD_URL`                                                    | Jira-specific PAC/WPAD overrides                                 |
| `CONFLUENCE_HTTP_PROXY`, `CONFLUENCE_HTTPS_PROXY`, `CONFLUENCE_SOCKS_PROXY`, `CONFLUENCE_NO_PROXY` | Confluence-specific explicit proxy overrides                     |
| `CONFLUENCE_PROXY_WPAD_ENABLE`, `CONFLUENCE_PROXY_WPAD_URL`                                        | Confluence-specific PAC/WPAD overrides                           |

Service-specific variables override global ones. PAC/WPAD is opt-in and is
only evaluated when no explicit proxy is configured for that service.
PAC/WPAD support is provided by the optional `wpad` extra. Install it with
`pip install "mcp-atlassian[wpad]"` or `uv add "mcp-atlassian[wpad]"` before
enabling the feature. The published Docker image includes this extra.

## Custom HTTP Headers

Add custom HTTP headers to all API requests. Useful in corporate environments.

| Variable                         | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `JIRA_CUSTOM_HEADERS`            | Custom headers for Jira requests                                         |
| `CONFLUENCE_CUSTOM_HEADERS`      | Custom headers for Confluence requests                                   |
| `JIRA_PASSTHROUGH_HEADERS`       | Incoming MCP request header names to pass through to Jira requests       |
| `CONFLUENCE_PASSTHROUGH_HEADERS` | Incoming MCP request header names to pass through to Confluence requests |

**Format:** Static custom headers use comma-separated `key=value` pairs.
Passthrough headers use comma-separated header names.

```bash theme={null}
JIRA_CUSTOM_HEADERS=X-Forwarded-User=service-account,X-Custom-Auth=token
CONFLUENCE_CUSTOM_HEADERS=X-Service=mcp-integration,X-ALB-Token=secret

# Header names only. Values are read from each incoming MCP HTTP request.
JIRA_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID
CONFLUENCE_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID
```

Passthrough headers are request-scoped and only apply to HTTP transports. If a
passthrough header name conflicts with a static custom header, the incoming
request header value is used for that request.

Only configure headers that are set by a trusted proxy or gateway. Clients can
control any passthrough header they are allowed to send to the MCP endpoint.
When external auth uses a client-supplied Jira or Confluence URL, configure
`MCP_ALLOWED_URL_DOMAINS`; dynamic URLs are rejected without this allowlist so
trusted session headers cannot be forwarded to an attacker-controlled host.

<Note>
  Header values are masked in debug logs for security.
</Note>

## Tool Filtering

Control which tools are available:

```bash theme={null}
# Enable specific tools
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# Read-only mode (disables all write operations)
READ_ONLY_MODE=true
```

Command-line alternative:

```bash theme={null}
uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue"
```

### Toolset Filtering

Toolsets provide group-level tool control. Instead of listing individual tool names,
enable entire groups of related tools at once using the `TOOLSETS` environment variable.

```bash theme={null}
# Restrict to core tools only (~35 tools across 6 core toolsets)
TOOLSETS=default

# Core tools plus agile boards/sprints
TOOLSETS=default,jira_agile

# Deprecated tools only, for migration compatibility
TOOLSETS=legacy

# Core tools plus deprecated tools during migration
TOOLSETS=default,legacy

# All toolsets (same as current default when TOOLSETS is unset)
TOOLSETS=all
```

Command-line alternative:

```bash theme={null}
uvx mcp-atlassian --toolsets "default,jira_agile"
```

**Core toolsets** (included with `TOOLSETS=default`):
`jira_issues`, `jira_fields`, `jira_comments`, `jira_transitions`, `confluence_pages`, `confluence_comments`

The opt-in **`legacy` toolset** contains deprecated tools retained while users
migrate to their replacement tools. Use `TOOLSETS=legacy` to expose only those
tools, or combine it with another selection such as `TOOLSETS=default,legacy`.
It is not included in `TOOLSETS=default`.

When both `TOOLSETS` and `ENABLED_TOOLS` are set, they intersect — a tool must pass
both filters. If `TOOLSETS` is not set, all toolsets are currently enabled.

<Warning>
  In v0.22.0, the default will change from all toolsets to 6 core toolsets only.
  Set `TOOLSETS=all` explicitly to preserve current behavior.
</Warning>

<Note>
  Unknown toolset names are silently ignored. If **all** names are unknown, no tools are
  enabled (fail-closed behavior to prevent accidental exposure).
</Note>

See [Toolset Groups](/docs/tools-reference#toolset-groups) for the full list of available toolsets.