Connect Google Sheets to Codex via MCP

Can Codex read a Google Sheet?

Yes. Codex supports remote MCP servers over Streamable HTTP, and PasteSheet turns a Google Sheet into one of those hosted endpoints. Add the endpoint URL to Codex and the agent can list tabs, inspect columns, and query rows while it works.

Start with a link-shared sheet, or connect Google and choose a restricted file in Picker. PasteSheet handles the spreadsheet connection and serves the MCP tools, so you do not create a Google Cloud project, install a local server, or paste rows into every prompt. For the protocol and product overview, see the Google Sheets MCP server guide.

Connect in four steps

1. 1 Create a PasteSheet endpoint from a public Google Sheet URL, or connect Google and select the exact restricted sheet in Picker.
2. 2 Open the endpoint's Connect via MCP panel and copy its /mcp/sheets/… URL.
3. 3 Run codex mcp add pastesheet --url <MCP URL>, or add the same URL to a project-scoped .codex/config.toml.
4. 4 Confirm the server with codex mcp list. Then open Codex, run /mcp, and ask a question about your sheet.

Add the server from the Codex CLI

Codex can register a hosted MCP server with one command. Replace the example endpoint id with the URL from PasteSheet:

codex mcp add pastesheet --url \
  https://pastesheet.com/mcp/sheets/your-endpoint-id

Scope the connection to one project

Codex normally stores MCP settings in ~/.codex/config.toml. For a trusted project that alone should use this sheet, put the server in .codex/config.toml instead:

[mcp_servers.pastesheet]
url = "https://pastesheet.com/mcp/sheets/your-endpoint-id"

Authenticate a private endpoint

Keep the key out of the config file. Put it in an environment variable, then tell Codex which variable supplies the bearer token:

[mcp_servers.pastesheet]
url = "https://pastesheet.com/mcp/sheets/your-endpoint-id"
bearer_token_env_var = "PASTESHEET_API_KEY"

Check that Codex can see the sheet

Run codex mcp list in your terminal to confirm that pastesheet is registered. Inside the Codex terminal UI, use /mcp to see the active server and its tools. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration on the same Codex host.

Then ask something concrete, such as “List the tabs and show me the newest ten active customers.” Codex should inspect the schema before querying the rows. If it cannot connect, confirm that you copied the MCP URL rather than the REST API URL and that the bearer environment variable is available to the Codex process.

The tools Codex gets

PasteSheet exposes three read-only tools, and Codex chooses the right one for each question:

• list_tabs discovers every tab and identifies the default one.
• get_schema returns clean column aliases and inferred types before a query runs.
• query_rows filters, searches, sorts, and paginates rows. Pro endpoints can also aggregate with count, sum, avg, and group_by.

Why use a hosted, read-only connection?

A direct Sheets API integration makes every developer solve credentials, range parsing, rate limits, and hosting before the agent can read one row. PasteSheet packages that work behind one remote URL and caches the source, so repeated tool calls do not become repeated requests to Google.

The tool boundary is intentionally narrow. Codex can query and analyse the spreadsheet, but PasteSheet exposes no write or delete tool. A coding agent can use live reference data without gaining a path to modify the source sheet.

Requirements

MCP is included on the Free plan. Connect any public endpoint over MCP with no Google Cloud project and no credit card. Private endpoints and the account-wide workspace server need a paid plan (from Starter ($9/mo)) for the keys and OAuth they authenticate with.

Pro adds full-text search and aggregation (count, sum, avg, group_by) that your AI agent can call through query_rows.

Frequently asked questions

Sources

• Model Context Protocol in Codex — OpenAI
• Model Context Protocol specification — Model Context Protocol

Related guides