HTTP Transport

Deploy MCP Atlassian as an HTTP service with SSE or streamable-http for multi-user and remote scenarios

Instead of using stdio, you can run the server as a persistent HTTP service. This enables multi-user scenarios and remote deployment.

Transport Types

Transport	Endpoint	Use Case
sse	/sse	Server-Sent Events, good for streaming
streamable-http	/mcp	HTTP-based, good for multi-user

Stateless Mode

For Kubernetes deployments or environments where session state should be ephemeral, use the --stateless flag with streamable-http transport:

# Using uvx
uvx mcp-atlassian --transport streamable-http --stateless --port 9000 -vv

# Or using Docker
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --stateless --port 9000 -vv

# Or via environment variable
STATELESS=true uvx mcp-atlassian --transport streamable-http --port 9000

The --stateless flag is only supported with streamable-http transport. Using it with stdio or sse will result in an error.

Basic Setup

SSE Transport

# Using uvx
uvx mcp-atlassian --transport sse --port 9000 -vv

# Or using Docker
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

IDE Configuration:

{
  "mcpServers": {
    "mcp-atlassian-http": {
      "url": "http://localhost:9000/sse"
    }
  }
}

Streamable-HTTP

# Using uvx
uvx mcp-atlassian --transport streamable-http --port 9000 -vv

# Or using Docker
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --port 9000 -vv

IDE Configuration:

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Multi-User Authentication

Both transport types support per-request authentication where each user provides their own credentials.

Authentication Methods

Cloud (OAuth)

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Server/DC (PAT)

Set a URL and a non-empty server-side PAT value for each enabled service:

JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=unused

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=unused

These values let the server build its URL, SSL, and proxy configuration at startup. The PAT sent with each request replaces the corresponding server-side value for that API call.

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

Keep ALLOW_GLOBAL_CRED_FALLBACK disabled when using placeholder values. Requests without a PAT are rejected by default; enabling fallback would use the server-side value as a credential.

Server Setup for Multi-User

1. Run OAuth Setup (if using OAuth)

   # Using uvx
   uvx mcp-atlassian --oauth-setup -v
   
   # Or using Docker
   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
   
2. Start HTTP Server

   # Using uvx (with env vars set)
   uvx mcp-atlassian --transport streamable-http --port 9000 -vv
   
   # Or using Docker
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv
   
3. Configure Environment

   JIRA_URL=https://your-company.atlassian.net
   CONFLUENCE_URL=https://your-company.atlassian.net/wiki
   ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
   ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
   ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
   ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
   ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard
   # Optional: enable MCP OAuth proxy + DCR/discovery endpoints
   ATLASSIAN_OAUTH_PROXY_ENABLE=true
   PUBLIC_BASE_URL=https://mcp.example.com/mcp-atlassian
   

OAuth Discovery + DCR for MCP Clients

When ATLASSIAN_OAUTH_PROXY_ENABLE=true, the HTTP service exposes OAuth discovery and DCR endpoints so MCP clients can onboard users through spec-aligned OAuth:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server
• POST /register
• GET /authorize
• POST /token
• callback route derived from ATLASSIAN_OAUTH_REDIRECT_URI

Use this for remote clients like ChatGPT/Codex that expect discovery + DCR.

The DCR client’s redirect_uri must be different from the OAuth proxy’s own IdP callback. If a client tries to register the proxy callback as its redirect URI, registration is rejected with invalid_redirect_uri to prevent a callback loop.

Multi-Cloud Support

For multi-tenant applications where each user connects to their own Atlassian cloud instance:

1. Enable minimal OAuth mode:

   # Using uvx
   ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000
   
   # Or using Docker
   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000
   

2. Users provide authentication via HTTP headers:

   • Authorization: Bearer <user_oauth_token>
   • X-Atlassian-Cloud-Id: <user_cloud_id>

Python Example

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"

async def main():
    async with streamablehttp_client(
        "http://localhost:9000/mcp",
        headers={
            "Authorization": f"Bearer {user_token}",
            "X-Atlassian-Cloud-Id": user_cloud_id
        }
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            result = await session.call_tool(
                "jira_get_issue",
                {"issue_key": "PROJ-123"}
            )
            print(result)

asyncio.run(main())

• Requests without user-specific credentials are rejected unless ALLOW_GLOBAL_CRED_FALLBACK=true
• User tokens are isolated per request - no cross-tenant data leakage
• Falls back to global ATLASSIAN_OAUTH_CLOUD_ID if header not provided