How to connect a Jira MCP with Codex (4 steps)

When developers hand off a task to Codex, they summarize the ticket. That summary is always lossy.

Edge cases get dropped, acceptance criteria get paraphrased, and linked tickets that affect the implementation get omitted entirely. Codex writes code against the developer's shorthand version of the requirements, not against what the ticket actually says.

Connecting Jira gives Codex direct access to the tickets that define the work. When a task requires implementation context, Codex reads the actual issue rather than relying on whatever the developer thought to include.

To give Codex direct access to Jira as it works through your coding tasks, we'll show you how to connect Jira with Merge Agent Handler's Jira MCP server.

How it works

Merge Agent Handler connects Codex to the Jira API through the Merge CLI. You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a Merge CLI section to your project's AGENTS.md file, which tells Codex when to call merge search-tools and merge execute-tool to reach Jira.

Once connected, Merge handles Atlassian OAuth credential storage and token refresh on your behalf, so you never embed credentials in the repo or deal with rotation yourself.

Related: How to use the Jira MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Codex access (available via the OpenAI platform)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Jira account with access to the projects you want Codex to query

If you want to connect Merge Agent Handler's Jira MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install with pipx: pipx install merge-api

Verify the installation: merge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account and stores your session credentials locally.

3. Add Agent Handler to Codex

Run the following from the root of the project where you want Codex to have access to Jira:

merge setup agents-md

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when a task requires Jira data. The command is idempotent — safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so the configuration travels with the repo.

Related: A guide to integrating the Jira MCP with Cursor

4. Authenticate Jira

Create a Codex task that requires live Jira data.

For example: "Read the acceptance criteria and linked issues in PROJ-412, then write the implementation and a matching test suite that covers each acceptance criterion."

The first time Codex invokes a Jira tool, a Magic Link will appear to complete connector authentication.

Once authenticated, Codex has access to your Jira projects through Merge for all subsequent tasks in this project.

{{this-blog-only-cta}}

Jira MCP FAQ

In case you have more questions on setting up and using the Jira MCP with Codex, we've addressed several more commonly-asked questions below.

What can you do once the Jira MCP is connected to Codex?

With Jira connected, Codex can:

• Read a ticket's acceptance criteria before writing the implementation: pull the full issue text at the start of a task so the generated code satisfies what the ticket actually specifies, not what the developer paraphrased in the task description

• Pull an epic's requirements before scaffolding a module: retrieve the parent epic and its linked child issues to understand the full scope before generating the module structure, so the scaffold reflects the real feature boundaries

• Read a bug report to generate a failing test that reproduces the issue: fetch the steps to reproduce, affected behavior, and expected outcome from the ticket, then write a test case targeting the specific condition described

• Pull sprint backlog details to produce an accurate implementation plan: retrieve the full set of issues in the current sprint, including descriptions and linked tickets, before generating a sequenced plan that accounts for actual dependencies

• Check linked issues before touching shared code: read the linked blockers or related tickets referenced in a story before making changes that could affect them, so the implementation respects existing constraints

Why use Merge Agent Handler vs. a self-hosted Jira MCP server?

You can stand up a self-hosted Jira MCP server and configure Codex to use it. That means generating an Atlassian API token, defining the tool schemas you need, and running a local or hosted MCP process. For a single developer on a personal project, that works.

It stops working cleanly when more than one developer is running Codex tasks against shared Jira projects.

Each developer needs their own API token, and there's no central place to define which projects or issue types a Codex task is permitted to read. When someone's token gets revoked or expires, the integration breaks for them and them alone, with no visibility into why.

Merge Agent Handler adds a managed layer on top: credential storage and token refresh handled by Merge, per-user authentication so each developer authenticates with their own Atlassian identity, and full audit logging on every tool call.

For engineering teams running Codex tasks against production Jira boards, that combination of scoped access and observability matters.

Why connect Jira to Codex?

Jira is where requirements live. Acceptance criteria, edge cases, linked issues, sprint priorities, etc. is in the ticket. When developers create a Codex task to implement a feature, they translate that ticket into a task description. That translation always leaves things out.

Codex has no way to recover what was dropped. It generates code against the task it received, not the ticket that defined the work. The output is directionally correct but wrong on specifics: field names that don't match the spec, edge cases that aren't handled, acceptance criteria that are partially satisfied at best.

Connecting Jira gives Codex direct access to the source of truth.

Instead of relying on the developer's summary, Codex reads the actual ticket: the full description, acceptance criteria, attachments, and linked issues. The implementation reflects what was actually specified.

Can I use Merge's Jira MCP with my employees?

Yes, Merge for Workforce is built to help engineering organizations provision, secure, and govern how employees connect AI tools like Codex to project management systems like Jira.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can read or act on Jira issues by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which projects or issue types a Codex task is permitted to access before results reach the agent's context

• User-level audit logging so security and IT teams can review which issues were read, which epics were queried, and which sprint data was retrieved, by which employee identity, and when

Taken together, employees can use the Jira MCP to have Codex read tickets before implementation, pull sprint context before planning, and generate tests from bug reports, while IT keeps centralized control over which projects and issue types each developer's agent can reach.