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

Customer bug reports, vendor API change notices, product feedback, and technical escalations arrive over email and get discussed in threads.

When developers create a Codex task to act on one of these, they summarize what they remember. But the original thread, with the exact error messages, reproduction steps, and back-and-forth context, is still in Gmail.

Codex writes code against the developer's summary. The fix addresses what the developer described, not what the email thread actually documented.

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

How it works

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

Once connected, Merge handles credential storage and Gmail OAuth token refresh on your behalf, so no credential state lives in your repo.

Related: How to use the Gmail 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 Google account with Gmail access

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

1. Install the Merge CLI

Run the following to install the Merge CLI: 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 account so Merge can make authorized requests against Gmail on your behalf.

3. Add Agent Handler to Codex

From the root of the project where you want Codex to have access to Gmail, 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 Gmail 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 Gmail MCP with Cursor

4. Authenticate Gmail

Create a Codex task that requires live Gmail data, something like: "Read the bug report email thread about the payment processing timeout error from last week and generate a fix, including a regression test that covers the exact failure conditions described."

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

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

{{this-blog-only-cta}}

Gmail MCP FAQ

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

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

With Gmail connected, Codex can:

• Read a bug report thread before generating a fix: pull the full email conversation, including all replies, so the generated fix addresses the specific error conditions and reproduction steps discussed in the thread rather than a developer's paraphrase of them

• Pull a feature request email chain before scaffolding an implementation: retrieve the original request thread and any follow-up discussion so the scaffolded code reflects what was actually asked for, including edge cases and constraints that came up in replies

• Read a customer escalation thread to generate a response template: fetch the escalation chain, including the customer's messages and any internal replies, so the generated template matches the tone and addresses the specific concerns raised, not a generic template built from memory

• Pull API change notification emails before updating integration code: retrieve vendor notification threads that document a breaking change or deprecation so the updated integration code reflects the actual new behavior described, rather than assumptions based on what the developer recalls reading

• Read an incident report thread to generate a runbook entry: fetch the thread that documents how an outage was diagnosed and resolved so the generated runbook captures the real steps taken, not a reconstruction from the developer's recollection

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

You can build a self-hosted Gmail MCP server using open-source packages that wrap the Gmail API directly. For a single developer on a personal project, that setup is workable: create a Google Cloud project, configure OAuth credentials, stand up the server, and point Codex at it.

The overhead compounds at the team level. Gmail OAuth requires a Google Cloud project with correctly scoped credentials and token refresh logic. If multiple developers need Gmail access, each manages their own credentials, or tokens get shared in ways that are hard to audit and revoke cleanly.

Merge Agent Handler handles credential storage and OAuth refresh centrally, so no individual developer manages token state. Every tool call Codex makes against Gmail is logged, you can define which operations each agent is allowed to perform, and you can revoke access from one place.

For teams where Codex tasks might touch customer communications, support inboxes, or shared team aliases, that combination of access scoping and audit logging is what makes a production deployment defensible rather than just functional.

Why connect Gmail to Codex?

Most engineering teams treat email as an informal record, but it's often where the most detailed technical context actually lives.

The bug report that came in before a Jira ticket was created, the vendor email documenting a breaking API change, the customer escalation thread with the specific reproduction steps: all of that context is in Gmail, not in whatever the developer typed into the Codex task description.

When Codex doesn't have access to the source, it writes against whatever context the developer provided. That context is always compressed. Connecting Gmail gives Codex the ability to retrieve the original thread when a task calls for it, so the output reflects the actual documentation rather than a developer's summary of it.

The difference shows up on precision tasks: generating a fix that covers specific edge cases from a bug report, updating integration code against the exact API changes a vendor described, or producing a response template that addresses the particular concerns a customer raised. Those tasks require the original thread, and Codex can now get it.

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

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to communication systems like Gmail.

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 mailboxes, labels, or shared inboxes by role or team

• DLP and policy enforcement on tool calls, so admins can block Codex tasks from reading threads outside their designated scope or prevent retrieval of customer communications before they reach the agent's context

• User-level audit logging so security and IT teams can review which threads were read, which messages were retrieved, and which Gmail data was accessed, by which employee identity, and when

The result is that employees can use the Gmail MCP to generate fixes grounded in real bug report threads, produce code updates based on actual vendor notifications, and build response templates from live escalation context, while IT keeps centralized control over which inboxes and message data each developer's agent can reach.