How to Add the Atlassian MCP Server to Codex CLI

TL;DR — the two-minute setup

Codex reads MCP servers from one file, ~/.codex/config.toml. The Atlassian MCP server is remote and OAuth-secured, so the reliable path is to bridge it with mcp-remote. One command:

codex mcp add atlassian -- npx -y mcp-remote https://mcp.atlassian.com/v1/mcp/authv2

Then start codex. A browser tab opens, you approve Atlassian’s OAuth consent screen, and the Jira + Confluence tools appear. Confirm with /mcp inside the session. If your Codex build supports remote MCP OAuth natively, there’s an even cleaner path (a url block plus codex mcp login) — both are covered below. Everything else in this guide is the detail behind those two lines: prerequisites, the OAuth flow, verifying it, adding Jira and Confluence specifically, and the errors people actually hit.

What the Atlassian MCP server does

The Atlassian MCP server exposes Jira and Confluence to an AI client as callable tools. Once connected, Codex can search issues with JQL, read and create issues, transition statuses, add comments and worklogs, and search, read, and write Confluence pages — all as you, bounded by your existing Atlassian permissions. It is Atlassian’s own remote server, hosted at mcp.atlassian.com, not a local package you run. That single fact drives the whole setup: there is no npm install, no binary — you point Codex at a URL and authenticate over OAuth 2.1. For the full server overview (both the official server and the community alternative for Server/Data Center), see our Jira MCP server guide; this page is only about wiring it into Codex.

Prerequisites

• Codex CLI installed. Install or update with npm i -g @openai/codex. Older builds have rougher MCP handling on Windows — update first. Start a session once with codex to create ~/.codex/config.toml if it doesn’t exist. Not set up yet? Our Codex client page has the base configuration.
• Node.js 18+. The mcp-remote bridge runs under npx, so you need Node on your PATH. Check with node --version.
• An Atlassian Cloud site. The official server connects to Cloud only — a *.atlassian.net site with Jira and/or Confluence. Jira Server or Data Center is not supported by this server (use the community server for on-prem, covered in the guide linked above).
• A browser on the same machine for the one-time OAuth consent. For headless/CI, use the API-token path in the errors section.

Add it to Codex CLI

There are two ways to register the server. Method A works on every Codex version. Method B is cleaner but needs a recent build that speaks remote MCP OAuth. Pick one.

Method A — the mcp-remote bridge (works everywhere)

codex mcp add registers a stdio command; mcp-remote is a small Node proxy that turns Atlassian’s OAuth HTTP endpoint into that stdio command and handles the browser round-trip. Run:

codex mcp add atlassian -- npx -y mcp-remote https://mcp.atlassian.com/v1/mcp/authv2

That writes a table into ~/.codex/config.toml. You can also hand-write it — identical result:

[mcp_servers.atlassian]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp/authv2"]
startup_timeout_sec = 60   # optional; the first cold npx run can be slow

One opinionated note: raise startup_timeout_sec from its default of 10. The first run downloads mcp-remote and opens a browser, which routinely blows a 10-second handshake budget. Sixty seconds removes a whole class of “request timed out” confusion.

Method B — native url + codex mcp login (recent Codex)

Newer Codex builds can talk to a streamable-HTTP MCP server directly and run the OAuth flow themselves, no Node bridge. Per OpenAI’s Codex MCP docs, a remote server is a url table:

[mcp_servers.atlassian]
url = "https://mcp.atlassian.com/v1/mcp/authv2"

Then authenticate with the login subcommand, which opens the browser consent screen:

codex mcp login atlassian

Codex stores the resulting token according to mcp_oauth_credentials_store (auto, file, or keyring) from the config reference. Honest caveat: adding a remote OAuth server through the CLI in one shot is still maturing — there’s an open request to give codex mcp add a --url/--oauth flag (issue #23846). Until that lands, Method A is the path that never surprises you.

The canonical server card — the same one on our Atlassian server page — is below. It’s the quick reference for GUI clients; for Codex, use the exact config.toml blocks above, since Codex needs the remote-server config rather than a local package.

One-line install · Atlassian (Jira & Confluence)

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Complete the OAuth login

Atlassian’s server uses OAuth 2.1 as its primary authentication, so the token is bound to your identity and every action respects your existing project and space roles. The flow, whichever method you chose:

1. Start Codex (Method A) or run codex mcp login atlassian (Method B). A browser tab opens to Atlassian’s consent screen.
2. Sign in if needed, pick the Atlassian site to grant, and approve. The tab shows a success page you can close.
3. The token is cached — Method A stores it under ~/.mcp-auth (mcp-remote’s cache), Method B under Codex’s credential store. Subsequent sessions reuse it; you don’t re-authenticate every run.

If the browser never opens on a remote or headless box, set a fixed callback port so you can forward it — mcp_oauth_callback_port is a top-level key in config.toml. And if a browser genuinely isn’t available, switch to the API-token path in the errors section.

Verify it works

Two checks — one from the terminal, one from a prompt. First, list what Codex parsed and connected:

codex mcp list           # atlassian should appear, connected
codex mcp get atlassian  # shows the resolved config for one server

Inside a Codex session, /mcp shows the same view plus the tool names. Then prove the round-trip with a real request — the canonical first prompt:

> List my open Jira issues, newest first, with key, status, and assignee.

Codex compiles that to a JQL query, calls searchJiraIssuesUsingJql, and prints a real table from your instance. If you get rows back, the connection, the OAuth grant, and your permissions all check out. If the tools aren’t there, jump to common errors — the OAuth step is the usual culprit.

Add Jira to Codex

There is no separate “Jira MCP” to install for Codex — Jira is part of the one Atlassian server you already added. Finish the setup above and the Jira tool surface is live. The ones you’ll actually use, from Atlassian’s supported-tools reference:

• searchJiraIssuesUsingJql — the workhorse. Every “find me…” request compiles to this.
• getJiraIssue, getVisibleJiraProjects, getTransitionsForJiraIssue — read paths.
• createJiraIssue, editJiraIssue, transitionJiraIssue, addCommentToJiraIssue — write paths.

A prompt that exercises write access, from inside a Codex session in your repo:

> Read PAY-1421 from Jira, implement the change it describes in this
  codebase, then transition the issue to "In Review" and add a comment
  linking the files you touched.

This is the “codex add jira mcp” workflow people are actually after: issue-driven development where the ticket is context and the status update is a tool call, not a context switch. The failure mode to know: hallucinated custom field names surface immediately as a JQL parse error, and the agent self-corrects in one round-trip.

Add Confluence

Confluence rides the same connection — no second server, no second login. Once the Atlassian server is authenticated, Codex has the Confluence tools too: searchConfluenceUsingCql, getConfluencePage, createConfluencePage, and updateConfluencePage, plus comment tools. If you only use Jira, you can ignore them; they cost nothing when unused.

A recipe that ties both products together in one prompt:

> Summarize everything that moved to Done in project PAY this week,
  then write it up as a new Confluence page titled "PAY — Weekly Ship
  Log" under the Engineering space.

Codex runs a JQL search, drafts the summary, and calls createConfluencePage. One caveat worth setting expectations on: the server is pull-and-push on request, not event-driven — there are no webhooks, so Codex reads and writes when you ask, it doesn’t react to Jira changes on its own.

Common errors and fixes

Community signal

Three sources, each a public, verifiable artifact — the maintainer’s framing, a Codex-specific walkthrough, and an honest look at where the tooling is still rough.

Frequently asked questions

Sources & further reading

Primary — Atlassian

• github.com/atlassian/atlassian-mcp-server — the official remote server; confirms the /v1/mcp/authv2 (OAuth) and /v1/mcp (API-token) endpoints and the hosted-only model.
• Atlassian Rovo MCP Server — getting started — OAuth 2.1, prerequisites, Cloud-only support.

Primary — OpenAI Codex

• developers.openai.com/codex/mcp — codex mcp add, the stdio and streamable-HTTP TOML schema, startup_timeout_sec.
• developers.openai.com/codex/config-reference — url, bearer_token_env_var, mcp_oauth_callback_port, mcp_oauth_credentials_store.

Community & walkthroughs

• Codex CLI and Jira: issue-driven development with the Atlassian MCP server — a Codex-specific tutorial (mcp-remote, browser OAuth).
• Composio — how to use MCPs with Codex — codex mcp login and native url config.
• openai/codex #23846 — feature request to add a --oauth flag to codex mcp add.
• r/atlassian — “Atlassian MCP server always just 429’s” — rate-limit reports.
• First-party X post: @Atlassian, March 2, 2026

Internal

• /servers/atlassian-jira-confluence — canonical server page
• /clients/codex — Codex client setup
• Jira MCP server guide — official vs community, tools, JQL recipes
• Codex MCP on Windows fix guide — every Windows failure mode
• Codex CLI config validator — paste-and-check your config.toml