How to connect a Google Sheets MCP with Codex (4 steps)

When developers create a Codex task, they summarize what the spreadsheet says. This leads Codex to generate code against the developer's description, not against the actual values in the cells.

The result is implementation that's plausible but wrong on the specifics: column names that don't match, enum values that aren't real, transformation rules that paraphrase rather than replicate what the sheet defines.

Connecting Google Sheets gives Codex direct access to those source tables. When a task requires field definitions, config values, or test data from a spreadsheet, Codex reads the actual sheet rather than working from a second-hand account of it.

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

How it works

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

Once connected, Merge handles OAuth token storage and refresh on your behalf, so you never configure a Google Cloud project or embed credentials in your repo.

Related: How to use the Google Sheets 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 access to the spreadsheets you want Codex to read

If you want to connect Merge Agent Handler's Google Sheets 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

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

4. Authenticate Google Sheets

Create a Codex task that requires live Sheets data. For example: "Read the field mapping sheet at [spreadsheet URL] and generate a TypeScript transformer function that converts each source field to its target field name, applying the transformation rules defined in the 'Transform' column."

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

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

{{this-blog-only-cta}}

Google Sheets MCP FAQ

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

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

With Google Sheets connected, Codex can:

• Read a data requirements sheet before generating processing logic: pull the actual field definitions, data types, and validation rules from a spreadsheet so the generated code handles the correct fields and types rather than the developer's paraphrase of them

• Pull a config spreadsheet to generate feature flag constants: retrieve the live config table with flag names, default values, and environment overrides to produce constants or configuration objects that match what the sheet actually defines

• Read a field mapping sheet to produce transformation logic: fetch the source-to-target column mappings from a spreadsheet and generate a transformer that applies the exact rules defined in each row, including conditional transformations or format conversions the sheet specifies

• Pull a test data sheet to generate fixture files: retrieve representative rows from a test dataset spreadsheet and use the actual values, including edge cases documented in the sheet, to produce fixture files or seed scripts for the test suite

• Read a data dictionary before scaffolding a schema: fetch the authoritative field names, types, and descriptions from a data dictionary spreadsheet to generate database schemas, ORM models, or GraphQL types with the correct definitions rather than inferred ones

• Pull a rules table to generate a decision engine: read a spreadsheet that encodes business rules as rows with condition and outcome columns, then generate the branching logic that implements those rules exactly as the table specifies

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

You can configure a self-hosted MCP server against the Google Sheets API and point Codex at it. For a solo developer working against their own spreadsheets, that setup works: create a Google Cloud project, configure OAuth credentials, write tool schemas for the operations you need.

The control problem surfaces when teams use Codex on projects where spreadsheets hold operational data. Google OAuth credentials at the project level grant access to every spreadsheet the account can reach. There is no mechanism to restrict a task to a specific sheet or to prevent Codex from reading tabs that are out of scope for the task.

Merge Agent Handler adds a managed layer on top. Credential storage and OAuth refresh are handled by Merge. Each developer authenticates with their own identity, so revoking one person's access doesn't affect anyone else's configuration. Every tool call is logged with the timestamp, inputs, and response metadata.

For teams running Codex against spreadsheets that hold canonical field definitions, config values, or test datasets, that audit trail matters. Knowing which sheet a Codex task read, and which values it used to generate code, is meaningfully different from having no record of what context the agent used.

Why connect Google Sheets to Codex?

A lot of engineering source-of-truth lives in spreadsheets: field mappings, data dictionaries, feature flag configs, transformation rules, test datasets.

Those documents exist because spreadsheets are fast to edit and easy for non-engineers to maintain. But Codex has no access to any of it unless the developer manually copies the relevant parts into the task.

That copy step is always partial. Developers summarize column names, skip rows that seem obvious, and describe transformation rules in their own words. Codex writes code against that summary, not against the actual values in the sheet.

Connecting Google Sheets gives Codex the ability to pull those source tables directly when a task requires them. The field mapping that defines the ETL transform, the config table that specifies feature flag defaults, the test dataset that covers the edge cases: Codex reads the original rather than a developer's interpretation of it. The generated code reflects what the spreadsheets actually say.

Can I use Merge Agent Handler's Google Sheets 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 operational spreadsheets like Google Sheets.

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 spreadsheets and tabs by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which sheets a Codex task can read and block retrieval of confidential content before it reaches the agent's context

• User-level audit logging so security and IT teams can review which spreadsheets were accessed, which ranges were read, by which employee identity, and when

In practice, employees can use the Google Sheets MCP in Codex to generate transformation logic from mapping sheets, scaffold schemas from data dictionaries, and produce fixture files from test datasets, while IT keeps centralized control over which spreadsheets each developer's agent can reach.