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

Linear issues contain the actual requirements: the acceptance criteria, the edge cases the product team debated, the linked issues that establish dependencies, and the comments where scope decisions got made.

When developers create a Codex task, they describe the issue from memory. That description loses the specifics.

Codex writes against what the developer typed, not against what the issue actually says. The result is implementations that address a general interpretation of the requirements rather than the exact scope and conditions the issue documents.

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

How it works

Merge Agent Handler connects Codex to the Linear 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 Linear.

Once authenticated, Merge handles OAuth credential storage and token rotation on your behalf, so you never embed credentials in your repo or manage refresh cycles yourself.

Related: How to use the Linear 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 Linear account with sufficient workspace permissions

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

1. Install the Merge CLI

Install the CLI with pipx: pipx install merge-api

Verify it installed correctly: merge --version

2. Log in to Merge

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

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

3. Add Agent Handler to Codex

From the root of the project where you want Codex to have access to Linear, run:

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 Linear data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so every developer and CI environment that runs Codex gets the same tool configuration.

Related: A guide to integrating the Linear MCP with Cursor

4. Authenticate Linear

Create a Codex task that requires live Linear data. This can be something like: "Read the acceptance criteria and linked issues for LIN-412 and scaffold the implementation, including unit tests that cover each acceptance criterion."

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

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

{{this-blog-only-cta}}

Linear MCP FAQ

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

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

With Linear connected, Codex can:

• Read an issue's description and acceptance criteria before scaffolding the implementation: pull the full issue body, including the conditions of satisfaction and any linked design references, so the generated code is scoped to what the issue actually specifies rather than what the developer paraphrased

• Pull a project's open issues to generate an accurate implementation plan: fetch all issues under a project, including their priorities and dependencies, so Codex can produce a sequenced plan that reflects what's actually in scope before a single line of code is written

• Read a bug report's details before writing a fix: retrieve the full issue body and comment thread, including the reproduction steps and any prior investigation notes, so the fix addresses the specific failure conditions documented rather than a general interpretation of the bug

• Pull a cycle's issues to generate release notes: fetch the set of issues completed in a given cycle, including their titles and descriptions, so release notes reflect what actually shipped rather than what the developer recalls from memory

• Read linked issues to understand dependencies before generating integration code: retrieve the issues an implementation depends on, including their descriptions and current status, so Codex can account for in-progress work and avoid generating code that assumes a dependency is already complete

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

You can build a self-hosted Linear MCP server that calls Linear's API directly. For a single developer authenticating with their own API key, that setup is straightforward: generate a token, define the tool schemas you need, and point Codex at the server.

The self-hosted path breaks down at team scale. Linear API keys are per-user, so every developer manages their own. There's no central place to scope which projects or issue data a given Codex task is allowed to reach, no audit trail of what the agent read, and no clean revocation path when someone leaves the team.

Merge Agent Handler adds a managed layer: Merge handles OAuth credential storage and refresh, each developer authenticates with their own identity, and every tool call is logged with the timestamp, tool name, and inputs.

For teams running Codex on a shared Linear workspace where issues contain sprint plans, roadmap decisions, or product specs, that audit trail matters.

Why connect Linear to Codex?

Most engineering teams use Linear as the canonical record of what needs to be built: the requirements, the acceptance criteria, the dependencies, and the decisions made during planning.

Codex doesn't have access to any of that unless a developer manually copies it into the task description.

That copy step is the source of problems. Developers paraphrase, omit edge cases, and leave out the linked issues where scope was clarified. Codex writes against the paraphrase, not the source.

Connecting Linear gives Codex the ability to pull the source issue directly when a task requires it. The acceptance criteria for the feature being implemented, the bug report that documents the failure conditions, the cycle's issue list that defines what a release covers: Codex reads the original rather than the developer's interpretation of it.

The output reflects what the issues actually specify. That closes the gap between what the team planned and what gets built.

Can I use Merge Agent Handler's Linear MCP with my employees?

Yes, Agent Handler for Employees is built to help engineering organizations provision, secure, and govern how employees connect AI tools like Codex to project management systems like Linear.

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 access which Linear teams, projects, and cycles by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which projects or issue data a Codex task is allowed to reach, or block retrieval of confidential roadmap content before it reaches the agent's context

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

In practice, employees can use the Linear MCP to generate implementations grounded in real issue requirements, produce release notes from live cycle data, and scaffold features against the actual acceptance criteria the product team wrote, while IT keeps centralized control over which teams and projects each developer's agent can reach.