### Prompt for AI coding agents to set up Atlassian MCP

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Copy and paste this prompt into your AI coding agent to install, authenticate, and set up Atlassian MCP automatically. The agent will use the official setup guide and the MCP server URL to configure itself and start the authentication flow.

```text
Set up Atlassian MCP for this agent using the official setup guide at https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/ and the MCP server URL https://mcp.atlassian.com/v2/mcp. Then start the Atlassian MCP authentication flow so I can sign in.
```

--------------------------------

### Legacy Atlassian MCP configuration with authv2 endpoint

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/how-to-upgrade-from-atlassian-mcp-v1-to-atlassian-mcp-v2

Example of an existing MCP configuration that exposes the legacy Atlassian MCP endpoint https://mcp.atlassian.com/v1/mcp/authv2. Replace the url or serverUrl value with https://mcp.atlassian.com/v2/mcp and then reauthenticate using /mcp or similar commands.

```json
{   "mcpServers": {     "atlassian": {       "url": "https://mcp.atlassian.com/v1/mcp/authv2"     }   } }
```

--------------------------------

### Configure MCP client with service account API key

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/configure-authentication-via-api-token

Add this configuration to your MCP client's mcp.json file. Replace YOUR_API_KEY_HERE with your service account API key.

```json
{   "mcpServers": {     "atlassian-mcp": {       "url": "https://mcp.atlassian.com/v2/mcp",       "headers": {         "Authorization": "Bearer YOUR_API_KEY_HERE"       }     }   } }
```

--------------------------------

### MCP client configuration with OAuth bearer token

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/configure-oauth-2-1

JSON configuration for an MCP client to connect to Atlassian MCP using OAuth 2.1. Replace YOUR_OAUTH_ACCESS_TOKEN with a valid access token obtained from the OAuth flow, for example via the authorization code grant.

```json
{   "mcpServers": {     "atlassian-mcp": {       "url": "https://mcp.atlassian.com/v2/mcp",       "headers": {         "Authorization": "Bearer YOUR_OAUTH_ACCESS_TOKEN"       }     }   } }
```

--------------------------------

### Atlassian MCP server URL for other clients

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Use this server URL for other MCP-compatible clients that support manual configuration.

```text
https://mcp.atlassian.com/v2/mcp
```

--------------------------------

### Atlassian MCP URL to expose all tools

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Use this override URL when utilising an MCP gateway to expose all tools available in Atlassian MCP in a paginated flat tool list, rather than using the discovery and execute methods.

```text
https://mcp.atlassian.com/v2/mcp?tools=all
```

--------------------------------

### listCodeDirectory

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools

Lists the files and subfolders under a path in a connected repository, page by page.

```APIDOC
## listCodeDirectory

### Description
Lists the files and subfolders under a path in a connected repository, page by page.

### Authentication
- **Available using:** OAuth 2.1
- **Required scope:** `search:code:agent-interface`
```

--------------------------------

### Claude Desktop MCP server configuration

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Add this configuration to your Claude Desktop config file to manually set up the Atlassian MCP server. The server URL is https://mcp.atlassian.com/v2/mcp.

```json
{   "mcpServers": {     "atlassian": {       "url": "https://mcp.atlassian.com/v2/mcp"     }   } }
```

--------------------------------

### Windsurf MCP server configuration

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Add this configuration to your Windsurf settings to set up the Atlassian MCP server as a custom server. The server URL is https://mcp.atlassian.com/v2/mcp/.

```json
{   "mcpServers": {     "atlassian": {       "serverUrl": "https://mcp.atlassian.com/v2/mcp/"     }   } }
```

--------------------------------

### Add Atlassian MCP server to Codex

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Run this command in your terminal to add the Atlassian MCP server to Codex. The server URL is https://mcp.atlassian.com/v2/mcp.

```bash
codex mcp add atlassian --url https://mcp.atlassian.com/v2/mcp
```

--------------------------------

### MCP client configuration with Basic auth

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/configure-authentication-via-api-token

JSON configuration for mcp.json to authenticate using a personal API token. Replace BASE64_ENCODED_EMAIL_AND_TOKEN with the base64-encoded value from Step 2.

```json
{
  "mcpServers": {
    "atlassian-mcp": {
      "url": "https://mcp.atlassian.com/v2/mcp",
      "headers": {
        "Authorization": "Basic BASE64_ENCODED_EMAIL_AND_TOKEN"
      }
    }
  }
}
```

--------------------------------

### Codex CLI migration script for Atlassian MCP v1 to v2

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/how-to-upgrade-from-atlassian-mcp-v1-to-atlassian-mcp-v2

Run this command in your local CLI to identify any local or global OAuth configurations for Atlassian MCP v1 and replace them with v2. Each modified configuration will open a browser window to authenticate. The script backs up the config file, skips configurations with bearer/basic token auth, and warns about timeout settings that are not restored.

```bash
new=https://mcp.atlassian.com/v2/mcp; re='^https://mcp[.]atlassian[.]com/v1/mcp(/authv2)?/?$'; cfg="${CODEX_HOME:-$HOME/.codex}/config.toml"; cp "$cfg" "$cfg.bak-$(date +%s)" && echo "Backed up $cfg" && codex mcp list --json | jq -r --arg re "$re" '.[]|select(.transport.type=="streamable_http")|select((.transport.url // "")|test($re))|[(if ((.transport.bearer_token_env_var // null)!=null) or ((((.transport.http_headers // {})+(.transport.env_http_headers // {})))!={}) then "SKIP" else "GO" end),.name,.transport.url,((.startup_timeout_sec // "-")|tostring),((.tool_timeout_sec // "-")|tostring)]|@tsv' | { auth=""; skipped=""; warn=""; while IFS=$'\t' read -r g n u st tt; do if [ "$g" = SKIP ]; then skipped="$skipped    $n  ($u)"$'\n'; continue; fi; echo "==> $n"; echo "    $u  ->  $new"; codex mcp remove "$n" || continue; codex mcp add "$n" --url "$new" || continue; auth="$auth    codex mcp login $n"$'\n'; [ "$st" != "-" ] && warn="$warn    [$n] startup_timeout_sec=$st not restored by 'codex mcp add'"$'\n'; [ "$tt" != "-" ] && warn="$warn    [$n] tool_timeout_sec=$tt not restored by 'codex mcp add'"$'\n'; done; if [ -n "$auth" ]; then echo; echo "Migrated to $new. Each 'codex mcp add' starts its own OAuth flow — complete the browser sign-in when prompted. To run any login again manually:"; echo; printf '%s' "$auth"; echo; echo "Verify with 'codex mcp list' (auth_status should leave not_logged_in); on rejection run 'codex mcp logout <name>' first."; else echo "No custom Codex MCP server on the v1 endpoints. Nothing to migrate."; fi; [ -n "$skipped" ] && { echo; echo "Left on v1 — bearer/basic token auth, documented only for v1/mcp:"; echo; printf '%s' "$skipped"; }; [ -n "$warn" ] && { echo; echo "Manual follow-up in $cfg:"; echo; printf '%s' "$warn"; }; }
```

--------------------------------

### search

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools

Semantic search across Jira, Confluence, and connected apps using natural language, through Rovo. This tool is in beta.

```APIDOC
## search

### Description
Semantic search across Jira, Confluence, and connected apps using natural language, through Rovo. This tool is in beta.

### Authentication
- **Available using:** OAuth 2.1 and API token authentication
- **Required scope:** `search:rovo:agent-interface`

### Notes
- Utilizing this tool may consume up to 10 Rovo credits.
```

--------------------------------

### Base64-encode email and API token

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/configure-authentication-via-api-token

Command to generate a base64-encoded string from the format 'email:api_token'. Replace the placeholder email and token with actual values.

```bash
# Format: email:api_token
echo -n "your.email@example.com:YOUR_API_TOKEN_HERE" | base64
```

--------------------------------

### Migrate Claude Code OAuth configurations from v1 to v2

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/how-to-upgrade-from-atlassian-mcp-v1-to-atlassian-mcp-v2

Run this command in your local CLI to identify local or global OAuth configurations for Atlassian MCP v1 and replace them with v2. You will need to reauthenticate after the update. The command backs up the configuration file, migrates servers, and prints instructions for authentication.

```bash
cfg="${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json"; new=https://mcp.atlassian.com/v2/mcp; re='^https://mcp[.]atlassian[.]com/v1/mcp(/authv2)?/?$'; m='to_entries[]|select((.value.url // "")|test($re))|[(if ((.value.headers // {})!={}) then "SKIP" else "GO" end),$s,$d,.key,(.value|.type=(.type//"http")|.url=$new|tojson)]|@tsv'; cp "$cfg" "$cfg.bak-$(date +%s)"; { jq -r --arg re "$re" --arg new "$new" --arg d "$HOME" --arg s user "(.mcpServers//{})|$m" "$cfg"; jq -r --arg re "$re" --arg new "$new" --arg s local '(.projects//{})|to_entries[]|select(.key|test("/[.]claude/plugins/")|not)|.key as $d|(.value.mcpServers//{})|'"$m" "$cfg"; jq -r '(.projects//{})|keys[]|select(test("/[.]claude/plugins/")|not)' "$cfg" | while read -r d; do [ -f "$d/.mcp.json" ] && jq -r --arg re "$re" --arg new "$new" --arg d "$d" --arg s project "(.mcpServers//{})|$m" "$d/.mcp.json"; done; } | { auth=""; skipped=""; while IFS=$'\t' read -r g s d n e; do if [ "$g" = SKIP ]; then skipped="$skipped    $n  ($s scope, $d)"$'\n'; continue; fi; echo "==> $n ($s scope, $d)"; (cd "$d" && claude mcp remove "$n" -s "$s" && claude mcp add-json "$n" "$e" -s "$s") || continue; if [ "$s" = user ]; then auth="$auth    claude mcp login $n"$'\n'; else auth="$auth    (cd $d && claude mcp login $n)"$'\n'; fi; done; if [ -n "$auth" ]; then echo; echo "Migrated to $new. v2 is a separate OAuth resource, so v1 credentials do NOT carry over — authenticate each one (the cd is required: local/project scoped servers only resolve from their own directory):"; echo; printf '%s' "$auth"; echo; echo "Or run /mcp inside Claude Code and pick the server by name. Verify with 'claude mcp get <name>'; on rejection run 'claude mcp logout <name>' first."; else echo "No custom Claude Code MCP server on the v1 endpoints. Nothing to migrate."; fi; [ -n "$skipped" ] && { echo; echo "Left on v1 — bearer/basic token auth, documented only for v1/mcp:"; echo; printf '%s' "$skipped"; }; }
```

--------------------------------

### searchCode

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools

Searches source code across connected source-control providers, returning the files that match and the specific lines within them.

```APIDOC
## searchCode

### Description
Searches source code across connected source-control providers, returning the files that match and the specific lines within them.

### Authentication
- **Available using:** OAuth 2.1
- **Required scope:** `search:code:agent-interface`
```

--------------------------------

### Add Atlassian MCP server to Claude Code

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server

Run this command in your terminal to add the Atlassian MCP server to Claude Code. After running it, execute /mcp once you've opened a Claude Code session to authenticate.

```bash
claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp
```

--------------------------------

### getCodeFile

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools

Reads the full contents of one file in a connected repository at a specific commit.

```APIDOC
## getCodeFile

### Description
Reads the full contents of one file in a connected repository at a specific commit.

### Authentication
- **Available using:** OAuth 2.1
- **Required scope:** `search:code:agent-interface`
```

--------------------------------

### scanCodeRepo

Source: https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools

Lists a repository's file paths at a specific commit, without reading any file contents.

```APIDOC
## scanCodeRepo

### Description
Lists a repository's file paths at a specific commit, without reading any file contents.

### Authentication
- **Available using:** OAuth 2.1
- **Required scope:** `search:code:agent-interface`
```