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

When developers hand a task to Codex, they write a description of what needs to be built. But that description is a summary of the issue, not the issue itself.

The ticket has acceptance criteria, linked issues, label context, milestone constraints, and discussion threads that shaped the spec. None of that makes it into the task description.

Codex writes against what it's given. If all it has is a developer's paraphrase, the implementation reflects the paraphrase, not the actual requirements. Connecting GitLab gives Codex direct access to the source so it can read the issue before it starts writing.

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

How it works

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

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

Related: How to use the GitLab 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 GitLab account with access to the projects you want Codex to query

If you want to connect Merge Agent Handler's GitLab 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 your 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 Merge 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 GitLab:

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 GitLab 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 GitLab MCP with Cursor

4. Authenticate GitLab

Create a Codex task that requires live GitLab data.

This can be something like: "Read issue #312 in the payments-service project, including its acceptance criteria and linked issues, then scaffold the feature implementation with the correct file structure and function signatures."

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

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

{{this-blog-only-cta}}

GitLab MCP FAQ

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

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

With GitLab connected, Codex can:

• Read a feature issue's requirements before scaffolding the implementation: pull the full issue body, acceptance criteria, and linked issues from GitLab at the start of a task so the generated code reflects what the ticket actually specifies, not what the developer summarized

• Pull an MR's description and linked issues to generate accurate release notes: retrieve the merge request details and its associated issue context to produce release notes that correctly describe what changed and why

• Read a project's existing CI pipeline config before generating additions: fetch the current .gitlab-ci.yml content from GitLab so any pipeline additions Codex generates follow the existing stage structure, variable conventions, and job templates already in use

• Pull issue labels and milestones to generate a correctly structured project tracker: read the label taxonomy and milestone definitions from GitLab to generate a tracker or reporting script that uses the project's actual label names and milestone IDs rather than guessed values

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

You can run a self-hosted GitLab MCP server and wire it to Codex directly. That means generating a personal access token, standing up an MCP process, and keeping both the token and the server available for every Codex task that needs them.

Where it breaks down is at the team level. A shared token has no per-user attribution, so you can't tell which Codex task read which issue, or which developer's agent made a change. Rotating that token means updating every developer's configuration at once.

Merge Agent Handler adds a managed layer: per-user authentication so each developer connects with their own GitLab identity, Merge-handled token storage and refresh so credentials never live in the repo, and full audit logging on every tool call.

For teams running Codex on production codebases, knowing exactly which issues were read during a generation task is meaningfully different from having no record of it.

Why connect GitLab to Codex?

GitLab is where the actual requirements live. Acceptance criteria, architectural notes, discussion threads, linked blockers—all of it is in the issue, not in the task description a developer writes when creating a Codex job.

Codex works best when it has the source, not a summary of it. Without GitLab access, it writes against whatever context the developer provided. With it, Codex can pull the issue directly and use what the ticket actually says.

That matters most for tasks where the details are load-bearing: issues with specific constraints that aren't obvious from the title, MRs with linked issues that explain why a change was made, CI jobs that reference variables defined elsewhere in the project. Connecting GitLab closes the gap between the spec and the implementation.

Can I use Merge's GitLab 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 GitLab.

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 GitLab projects and namespaces by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which projects or operations an employee's Codex agent can reach and block queries that would surface sensitive issue data before it reaches the agent's context

• User-level audit logging so security and IT teams can review which issues were read, which MRs were queried, and which pipeline configs were retrieved, by which employee identity, and when

Taken together, employees can use the GitLab MCP to read issue requirements before generating code, pull MR context for release notes, and query CI configs while building pipeline tooling, while IT keeps centralized control over which projects and namespaces each developer's agent can reach.