feat: add support for configuring custom HTTP headers (sooperset#570)

Add support for configuring custom HTTP headers for both Jira and 
Confluence API requests via environment variables. This enables users 
in corporate environments to add required authentication, routing, or 
security headers.

Changes:
- Add get_custom_headers() utility function for parsing comma-separated key=value pairs
- Add custom_headers field to JiraConfig and ConfluenceConfig classes  
- Apply custom headers to underlying session objects during client initialization
- Support service-specific headers via JIRA_CUSTOM_HEADERS and CONFLUENCE_CUSTOM_HEADERS
- Header values masked in debug logs to protect sensitive information
- Graceful handling of malformed headers (skip invalid, continue processing valid)
- Comprehensive test coverage with 470+ lines of tests
- Documentation with examples, debugging guide, and security considerations

Usage:
JIRA_CUSTOM_HEADERS=X-Corp-Auth=token123,X-Dept=engineering
CONFLUENCE_CUSTOM_HEADERS=X-ALB-Token=secret,X-Service=mcp-atlassian

This enables MCP server usage in corporate environments requiring 
additional HTTP headers for security, authentication, or routing.

Reported-by: Sajjad Pervaiz
Github-Issue: sooperset#436

Author: fgreinacher

.env.example

@@ -135,3 +135,10 @@ CONFLUENCE_URL=https://your-company.atlassian.net/wiki
 #CONFLUENCE_HTTPS_PROXY=https://confluence-proxy.example.com:8443
 #CONFLUENCE_SOCKS_PROXY=socks5://confluence-proxy.example.com:1080
 #CONFLUENCE_NO_PROXY=localhost,127.0.0.1,.internal.confluence.com
+
+# --- Custom HTTP Headers (Advanced) ---
+# Jira-specific custom headers.
+#JIRA_CUSTOM_HEADERS=X-Jira-Service=mcp-integration,X-Custom-Auth=jira-token,X-Forwarded-User=service-account
+
+# Confluence-specific custom headers.
+#CONFLUENCE_CUSTOM_HEADERS=X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token

README.md

@@ -373,6 +373,56 @@ Add the relevant proxy variables to the `args` (using `-e`) and `env` sections o
 Credentials in proxy URLs are masked in logs. If you set `NO_PROXY`, it will be respected for requests to matching hosts.
 
 </details>
+<details>
+<summary>Custom HTTP Headers Configuration</summary>
+
+MCP Atlassian supports adding custom HTTP headers to all API requests. This feature is particularly useful in corporate environments where additional headers are required for security, authentication, or routing purposes.
+
+Custom headers are configured using environment variables with comma-separated key=value pairs:
+
+```json
+{
+  "mcpServers": {
+    "mcp-atlassian": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "CONFLUENCE_URL",
+        "-e", "CONFLUENCE_USERNAME",
+        "-e", "CONFLUENCE_API_TOKEN",
+        "-e", "CONFLUENCE_CUSTOM_HEADERS",
+        "-e", "JIRA_URL",
+        "-e", "JIRA_USERNAME",
+        "-e", "JIRA_API_TOKEN",
+        "-e", "JIRA_CUSTOM_HEADERS",
+        "ghcr.io/sooperset/mcp-atlassian:latest"
+      ],
+      "env": {
+        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
+        "CONFLUENCE_USERNAME": "[email protected]",
+        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
+        "CONFLUENCE_CUSTOM_HEADERS": "X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token",
+        "JIRA_URL": "https://your-company.atlassian.net",
+        "JIRA_USERNAME": "[email protected]",
+        "JIRA_API_TOKEN": "your_jira_api_token",
+        "JIRA_CUSTOM_HEADERS": "X-Forwarded-User=service-account,X-Company-Service=mcp-atlassian,X-Jira-Client=mcp-integration"
+      }
+    }
+  }
+}
+```
+
+**Security Considerations:**
+
+- Custom header values are masked in debug logs to protect sensitive information
+- Ensure custom headers don't conflict with standard HTTP or Atlassian API headers
+- Avoid including sensitive authentication tokens in custom headers if already using basic auth or OAuth
+- Headers are sent with every API request - verify they don't interfere with API functionality
+
+</details>
+
 
 <details>
 <summary>Multi-Cloud OAuth Support</summary>
@@ -755,6 +805,43 @@ The server provides two ways to control tool access:
     - For older Confluence servers: Some older versions require basic authentication with `CONFLUENCE_USERNAME` and `CONFLUENCE_API_TOKEN` (where token is your password)
 - **SSL Certificate Issues**: If using Server/Data Center and encounter SSL errors, set `CONFLUENCE_SSL_VERIFY=false` or `JIRA_SSL_VERIFY=false`
 - **Permission Errors**: Ensure your Atlassian account has sufficient permissions to access the spaces/projects
+- **Custom Headers Issues**: See the ["Debugging Custom Headers"](#debugging-custom-headers) section below to analyze and resolve issues with custom headers
+
+### Debugging Custom Headers
+
+To verify custom headers are being applied correctly:
+
+1. **Enable Debug Logging**: Set `MCP_VERY_VERBOSE=true` to see detailed request logs
+   ```bash
+   # In your .env file or environment
+   MCP_VERY_VERBOSE=true
+   MCP_LOGGING_STDOUT=true
+   ```
+
+2. **Check Header Parsing**: Custom headers appear in logs with masked values for security:
+   ```
+   DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
+   ```
+
+3. **Verify Service-Specific Headers**: Check logs to confirm the right headers are being used:
+   ```
+   DEBUG Jira request headers: service-specific headers applied
+   DEBUG Confluence request headers: service-specific headers applied
+   ```
+
+4. **Test Header Format**: Ensure your header string format is correct:
+   ```bash
+   # Correct format
+   JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
+   CONFLUENCE_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
+
+   # Incorrect formats (will be ignored)
+   JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"  # Extra quotes
+   JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2  # Colon instead of equals
+   JIRA_CUSTOM_HEADERS=X-Custom = value1               # Spaces around equals
+   ```
+
+**Security Note**: Header values containing sensitive information (tokens, passwords) are automatically masked in logs to prevent accidental exposure.
 
 ### Debugging Tools
 

src/mcp_atlassian/confluence/client.py

@@ -114,6 +114,10 @@ def __init__(self, config: ConfluenceConfig | None = None) -> None:
             os.environ["NO_PROXY"] = self.config.no_proxy
             log_config_param(logger, "Confluence", "NO_PROXY", self.config.no_proxy)
 
+        # Apply custom headers if configured
+        if self.config.custom_headers:
+            self._apply_custom_headers()
+
         # Import here to avoid circular imports
         from ..preprocessing.confluence import ConfluencePreprocessor
 
@@ -158,6 +162,18 @@ def _validate_authentication(self) -> None:
             )
             raise MCPAtlassianAuthenticationError(error_msg) from e
 
+    def _apply_custom_headers(self) -> None:
+        """Apply custom headers to the Confluence session."""
+        if not self.config.custom_headers:
+            return
+
+        logger.debug(
+            f"Applying {len(self.config.custom_headers)} custom headers to Confluence session"
+        )
+        for header_name, header_value in self.config.custom_headers.items():
+            self.confluence._session.headers[header_name] = header_value
+            logger.debug(f"Applied custom header: {header_name}")
+
     def _process_html_content(
         self, html_content: str, space_key: str
     ) -> tuple[str, str]:

src/mcp_atlassian/confluence/config.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass
 from typing import Literal
 
-from ..utils.env import is_env_ssl_verify
+from ..utils.env import get_custom_headers, is_env_ssl_verify
 from ..utils.oauth import (
     BYOAccessTokenOAuthConfig,
     OAuthConfig,
@@ -35,6 +35,7 @@ class ConfluenceConfig:
     https_proxy: str | None = None  # HTTPS proxy URL
     no_proxy: str | None = None  # Comma-separated list of hosts to bypass proxy
     socks_proxy: str | None = None  # SOCKS proxy URL (optional)
+    custom_headers: dict[str, str] | None = None  # Custom HTTP headers
 
     @property
     def is_cloud(self) -> bool:
@@ -113,6 +114,9 @@ def from_env(cls) -> "ConfluenceConfig":
         no_proxy = os.getenv("CONFLUENCE_NO_PROXY", os.getenv("NO_PROXY"))
         socks_proxy = os.getenv("CONFLUENCE_SOCKS_PROXY", os.getenv("SOCKS_PROXY"))
 
+        # Custom headers - service-specific only
+        custom_headers = get_custom_headers("CONFLUENCE_CUSTOM_HEADERS")
+
         return cls(
             url=url,
             auth_type=auth_type,
@@ -126,6 +130,7 @@ def from_env(cls) -> "ConfluenceConfig":
             https_proxy=https_proxy,
             no_proxy=no_proxy,
             socks_proxy=socks_proxy,
+            custom_headers=custom_headers,
         )
 
     def is_auth_configured(self) -> bool:

src/mcp_atlassian/jira/client.py

@@ -128,6 +128,10 @@ def __init__(self, config: JiraConfig | None = None) -> None:
             os.environ["NO_PROXY"] = self.config.no_proxy
             log_config_param(logger, "Jira", "NO_PROXY", self.config.no_proxy)
 
+        # Apply custom headers if configured
+        if self.config.custom_headers:
+            self._apply_custom_headers()
+
         # Initialize the text preprocessor for text processing capabilities
         self.preprocessor = JiraPreprocessor(base_url=self.config.url)
         self._field_ids_cache = None
@@ -170,6 +174,18 @@ def _validate_authentication(self) -> None:
             )
             raise MCPAtlassianAuthenticationError(error_msg) from e
 
+    def _apply_custom_headers(self) -> None:
+        """Apply custom headers to the Jira session."""
+        if not self.config.custom_headers:
+            return
+
+        logger.debug(
+            f"Applying {len(self.config.custom_headers)} custom headers to Jira session"
+        )
+        for header_name, header_value in self.config.custom_headers.items():
+            self.jira._session.headers[header_name] = header_value
+            logger.debug(f"Applied custom header: {header_name}")
+
     def _clean_text(self, text: str) -> str:
         """Clean text content by:
         1. Processing user mentions and links

src/mcp_atlassian/jira/config.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass
 from typing import Literal
 
-from ..utils.env import is_env_ssl_verify
+from ..utils.env import get_custom_headers, is_env_ssl_verify
 from ..utils.oauth import (
     BYOAccessTokenOAuthConfig,
     OAuthConfig,
@@ -35,6 +35,7 @@ class JiraConfig:
     https_proxy: str | None = None  # HTTPS proxy URL
     no_proxy: str | None = None  # Comma-separated list of hosts to bypass proxy
     socks_proxy: str | None = None  # SOCKS proxy URL (optional)
+    custom_headers: dict[str, str] | None = None  # Custom HTTP headers
 
     @property
     def is_cloud(self) -> bool:
@@ -113,6 +114,9 @@ def from_env(cls) -> "JiraConfig":
         no_proxy = os.getenv("JIRA_NO_PROXY", os.getenv("NO_PROXY"))
         socks_proxy = os.getenv("JIRA_SOCKS_PROXY", os.getenv("SOCKS_PROXY"))
 
+        # Custom headers - service-specific only
+        custom_headers = get_custom_headers("JIRA_CUSTOM_HEADERS")
+
         return cls(
             url=url,
             auth_type=auth_type,
@@ -126,6 +130,7 @@ def from_env(cls) -> "JiraConfig":
             https_proxy=https_proxy,
             no_proxy=no_proxy,
             socks_proxy=socks_proxy,
+            custom_headers=custom_headers,
         )
 
     def is_auth_configured(self) -> bool:

src/mcp_atlassian/utils/env.py

@@ -49,3 +49,45 @@ def is_env_ssl_verify(env_var_name: str, default: str = "true") -> bool:
         True unless explicitly set to false values
     """
     return os.getenv(env_var_name, default).lower() not in ("false", "0", "no")
+
+
+def get_custom_headers(env_var_name: str) -> dict[str, str]:
+    """Parse custom headers from environment variable containing comma-separated key=value pairs.
+
+    Args:
+        env_var_name: Name of the environment variable to read
+
+    Returns:
+        Dictionary of parsed headers
+
+    Examples:
+        >>> # With CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"
+        >>> parse_custom_headers("CUSTOM_HEADERS")
+        {'X-Custom': 'value1', 'X-Other': 'value2'}
+        >>> # With unset environment variable
+        >>> parse_custom_headers("UNSET_VAR")
+        {}
+    """
+    header_string = os.getenv(env_var_name)
+    if not header_string or not header_string.strip():
+        return {}
+
+    headers = {}
+    pairs = header_string.split(",")
+
+    for pair in pairs:
+        pair = pair.strip()
+        if not pair:
+            continue
+
+        if "=" not in pair:
+            continue
+
+        key, value = pair.split("=", 1)  # Split on first = only
+        key = key.strip()
+        value = value.strip()
+
+        if key:  # Only add if key is not empty
+            headers[key] = value
+
+    return headers