# PM Backlog — MCP Atlassian Setup

This project connects Claude Code to Jira via the [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP server, running as a Docker container over streamable HTTP.

## Architecture

```
Claude Code  →  HTTP (localhost:9000/mcp)  →  Docker (mcp-atlassian)  →  Jira Cloud
```

The server uses the **streamable-http** transport (not stdio), which keeps the MCP server as a persistent process independent of Claude Code sessions.

## Prerequisites

- Docker and Docker Compose installed
- A Jira Cloud account with an API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens))

## Configuration

### Environment variables (`.env`)

| Variable | Description |
|---|---|
| `JIRA_URL` | Your Jira Cloud base URL (e.g. `https://your-org.atlassian.net`) |
| `JIRA_USERNAME` | Your Atlassian account email |
| `JIRA_API_TOKEN` | Your Atlassian API token |

OAuth2 variables are present but commented out — see the [OAuth2 section](#oauth2-future) below.

### Claude Code (`.mcp.json`)

Claude Code is configured to connect to the MCP server via:

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

This file is picked up automatically when Claude Code is opened in this directory.

## Running the server

**Start:**
```bash
docker compose up -d
```

**Stop:**
```bash
docker compose down
```

**View logs:**
```bash
docker compose logs -f
```

**Update to the latest image:**
```bash
docker compose pull && docker compose up -d
```

The server listens on `http://localhost:9000/mcp`.

## OAuth2 (future)

The mcp-atlassian server has built-in OAuth2 proxy support. When you are ready to enable it:

1. Uncomment the `ATLASSIAN_OAUTH_*` variables in `.env` and fill in your OAuth2 app credentials (created in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/)).
2. The server will expose standard OAuth2 discovery and token endpoints:
   - `GET /.well-known/oauth-authorization-server`
   - `POST /oauth/token`
   - `POST /oauth/register`
3. Place a reverse proxy (nginx, Caddy, etc.) in front of port 9000 to enforce bearer token validation before forwarding requests to `/mcp`.

Clients then authenticate with:
```
Authorization: Bearer <user_oauth_access_token>
```

For multi-tenant deployments, per-user Jira identity can be passed via:
```
X-Atlassian-Cloud-Id: <user_cloud_id>
```